librepcb / librepcb-doc

Official documentation of LibrePCB

LibrePCB Documentation

This repository contains the source for the LibrePCB documentation hosted at docs.librepcb.org.

Toolchain

The documentation is written in Asciidoc and built with Antora.

Unfortunately the build setup is not trivial since it is integrated into librepcb-website.

Therefore we created a Docker image containing the whole toolchain. On Linux, just make sure Docker is installed. Then building the documentation is as simple as calling this script:

./build.sh

Unfortunately on other operating systems it is much more complicated. However, having the toolchain available locally is not mandatory. A decent text editor (ideally with AsciiDoc syntax highligting and live preview) should be enough to write some documentation.

Virtual Machine For Screenshots

To ensure a consistent look&feel across all screenshots, please use a virtual machine (e.g. VirtualBox) and run LibrePCB within it. Set up the VM as following:

• Operating system: Ubuntu 22.04 (Choose "Minimal installation")
• Locale: English (en_US)
• Computer name: librepcb
• Full user name: Me
• Username: user

After the installation:

• Set the VM screen resolution to 1024x768 to ensure no screenshot is larger than this.
• On the bottom right of the login screen, switch from Wayland to X11 since most screenshot capture tools do not work properly on Wayland.
• Run sudo apt install shutter to install Shutter for capturing screenshots.
• In the Shutter settings, enable rounded corners.

Contributing

Contributions are very welcome! See our Contributing Guide for details. We're looking forward for pull requests :)

Links

• AsciiDoc Syntax Quick Reference
• Asciidoc Writer's Guide
• Antora Documentation
• Asciidoctor User Manual
• AsciidocFX (Asciidoc editor with live preview)

License

This documentation is published under the CC0 1.0 Universal license.

librepcb-doc's Issues

Installation of asciidoctor-pdf on MacOsx

Hello,

I followed the installation instructions on MacOSX :
**"On Mac you can use homebrew and install gems in your user folder:

brew install asciidoctor
gem install --user-install pygments.rb rouge"**

But to build the pdf file with the command "asciidoctor-pdf index.adoc # build index.pdf" it is also required to install asciidoctor-pdf on MacOSX

I would suggest to add in the installation part for MacOSX of the readme file this missing line: gem install asciidoctor-pdf

Best regards,
Pascal

Detail level of footprints

What should be part of a footprint apart from the functional parts?
Ideas:

• If #3 will not have a full outline, have the remaining outline in a documentation layer
• Thick lines in the documentation layer from plastic to pad (representing wings)?
• Keepout areas? I saw them a few times, what reasons are pro/con?

Conventions: Symbol pin order

When designing symbols (e.g. for the Blue Pill), how should the pins be sorted?

Some ways that come to mind:

• All on one side, sorted numerically
• On both sides, sorted numerically counterclockwise
• Matching the physical design
• Sorted logically (e.g. a group with I/O pins, all GND pins at the bottom, all power pins at the top, etc)

Any suggestions?

Add link to official online Gerber viewer

In production_data.adoc add a link to the Reference Gerber Viewer.

See LibrePCB/LibrePCB#215.

Screenshots are outdated or don't follow library conventions

Most screenshots were created with LibrePCB versions much older than the official 0.1.0 release, thus some of the screenshots are outdated.

In addition, we should check if the elements visible in the screenshots do actually correspond to our library conventions (which are still work in progress). It's annoying for users to see screenshots which do not follow our library conventions.

Specific issues:

• Component wizard shows "IC" as prefix for an OpAmp, while we actually use "U" for ICs.
• Component wizard shows "{{PARTNUMBER}}" as default value, while it should be "{{PARTNUMBER or DEVICE}}".

Footprint and pad orientation

It would be helpful if the documentation for creating a library specified whether the footprints and pin assignments should be made from a top-view or bottom-view. (It's top-view, right? Even for through-hole?)

Project files to add/ignore for version control

I appreciate that LibrePCB is very thoughtful about putting projects under version control. I'm looking for documentation (or a sample .gitignore) for my projects to avoid adding files that shouldn't be version-controlled.

For example, I noticed there are a number of very small dot files in my project directories (.librepcb-cmp, .librepcb-dev, etc). Should these be version controlled?

Conventions: Library organization

I would suggest one base repository which only includes abstract objects like "OpAmp Gate Symbol" and standard packages, and no actual devices. Most custom objects should reference these instead of creating their own.

Automate capture of screenshots for documentation

Using Funq and other machinery, automate the process of capturing screenshots against a given version of the software.

Conventions: Footprint / symbol line width

The current line width in the package and symbol editors is 0.25mm. Should we keep that? Is there a certain rationale for that choice?

In what cases should a library designer deviate from those values?

Conventions: Silkscreen Outline

When designing footprints, e.g. for an SOT-23-5:

...should we (1) include the outline of the plastic case in the footprint?

According to @ubruhin, "the solder mask is automatically subtracted from silkscreen to avoid silkscreen on copper", so this would work.

Or should we (2) make the rectangle smaller to avoid the pads?

Or should we (3) work with lines?

Add installation instructions for macOS

See LibrePCB/LibrePCB#250

Conventions: What orientation markings to use in footprints

There are different ways to implement orientation markings (for pin 1), e.g.

• mark at the short side of a DIP package
• dot in the corner
• chamferred edge

Should only one of these markers be included in the footprint or all possibilities?
The same part may have different markings depending on manufacturer (it may even be different for the same part from the same vendor), so I think it would be good to have all of them in one footprint.

Stop using GitBook.com

I already was never a fan of GitBook, but at least it was easy to quickly set up a documentation in AsciiDoc, and also we didn't have to care about hosting.

But now they massively changed their concept, see https://docs.gitbook.com/what-is-new/important-differences

This is really a shock, they removed all the nice features:

• CLI toolchain removed
• AsciiDoc support removed
• PDF/ebook export removed
• Multi-language books removed
• Plugins removed

I would say this is the time to move away from GitBook. But I still like AsciiDoc very much, I think we should just build and publish the page now on our own server...

Dificaulty in folowing LibrePCB "User Manual"

Please accept this as a helpful suggestion....

Section 2.4.3 Component does not work UNLESS one is instructed to "Save" at the end of Section 2.4.2. Symbol

Regards, Martin

Any kind of DXF or picture import?

Really Great software!

I though when checking it...the most important is here! But then I could not find any way if importing a PCB shape with reference holes via a DXF file etc. Maybe some other way? Through a picture, PDF, or anything that has the exact sizes to begin the board outline and mounting holes etc.

Did I miss something?

Move API documentation to doxygen.librepcb.org?

https://docs.librepcb.org is intended for user documentation. But is API documentation for users? Basically a user could also be interested in writing a script or so which fetches the list of available libraries from our server. But probably most users don't access the API directly, so I wonder if we should move the API documentation to our developers documentation at https://doxygen.librepcb.org to keep users documentation clean.

Actually I already gave it a try 😉, see https://doxygen.librepcb.org/_branches/add-api-documentation/d1/dcb/doc_server_api.html

Any thoughts?

EDIT: Actually the API specification is somehow similar to the file format specification, which is also documented at https://doxygen.librepcb.org...

Some terminology suggestions

Just reviewed the library spec (https://developers.librepcb.org/df/d4f/doc_library.html) These are great diagrams btw, I have a few suggestions:

Make the headings on the examples larger so they stand out. (The text at the top of the boundaries shown in grey)

'Splitted' - an awkward use of the term 'split' Would suggest using something like 'Separate', 'Separated', or 'Individual' instead.

'AllInOne' --> 'Combined'

'ReflowSoldering', 'WaveSoldering' - this is awkward as well in its verb form when it should be an adjective. Use ReflowSoldered, WaveSoldered instead. Reminds me of how the French mangled the term 'shampoo' and stuck 'ing' on their translation of it. : )

Minor: some labels are shown in CamelCase, others use whitespace to separate words. The former are class/interface names, the latter ones are just labels? Might need a consistency check or render them differently.

Split documentation into multiple pages

Currently the whole documentation is a single page and the TOC contains all subsections of all sections. This makes the documentation a bit confusing (I already removed some subsections from TOC just to improve readability).

I like the concept of ReadTheDocs which has a separate page for every top-level section. And the TOC shows subsections only for the currently opened top-level section.

Unfortunately this is not directly supported by asciidoctor...

Conventions: Standard Category Hierarchy

We should probably try to come up with a comprehensive and logical hierarchy of standard categories for both components and packages.

Those categories should probably be in the base library, so that all other libraries can reference them.

Coming up with this hierarchy might be tricky, since some concepts might be orthagonal. Maybe we should take inspiration from distributors, e.g. Digikey?

Conventions: Label alignment

I would add the following requirements:

• Generally, all symbols should have the {{ NAME }} label at the top and the {{ VALUE }} label at the bottom
• Generally, all packages should have the {{ NAME }} label at the top and the {{ VALUE }} label at the bottom
• For IC-like symbols, the labels should be aligned on the top and bottom line of the rectangle.

The question that already arose multiple times in practice was the question of left/right/center alignment. I feel that centering makes best use of the available screen and/or PCB space. This does not matter for short names, but it will for long names. Some examples:

Small symbol, short text:

Small symbol, long text:

Large symbol, short text:

Large symbol, long text:

Note that usually large symbols are much more "filled" with text, so the designator will look less "lost".

For packages, the labels can be moved around by the user, for symbols that's currently not possible.

Style wise I don't really care, I think that the small symbols look better centered and the larger ones look better left-aligned (maybe starting from a width of 8 * 2.54mm). We could make a rule of that, but it makes things more complicated for the user and costs more time during library contribution review.

However, from screen space usage there might be a clear "better".

Opinions, @ubruhin @rnestler @eduardosm @HBadertscher?

Add instructions for installation with Flatpak

LibrePCB can now also be installed with Flatpak, see LibrePCB/librepcb-rfcs#26.