Writing documentation¶

A great way to contribute without writing code is to help writing documentation. Please reach out before contributing as the software is still in an alpha state and portions may not be worth documenting as it changes too frequently.

Philosophy¶

The documentation is split into three sections:

Quickstart: a crash course where a user should be able to go from nothing to doing the most basic, common tasks. It is not comprehensive, but a highly focused tutorial style “taster” of what’s available. It should be kept very short, aiming to acquaint new users within an hour.
Guides: a guidebook style, topic-driven series of articles discussing things of interest, or tutorials that cover common workflows. This should contain lots of images.
Reference: a comprehensive index of the entire interface and all available features.

Documentation should not be a guide to IFC. Users should not have to know what IFC is.

Official documentation should be polished and maintained. Less documentation of a higher quality that is kept updated with every release is preferred to more documentation with stubs, incomplete or inaccurate information.

Syntax¶

All documentation is written in ReStructured Text and is available in the Bonsai docs directory. You can press the edit button on the top right on any documentation page to quickly edit their content.

Links¶

You can link to

`external websites
<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_

(note the space between the url and the link text). You can also link to sections on the same page, like

:ref:`contribute/writing_docs:Writing technical documentation`

or with

:ref:`custom text<contribute/writing_docs:writing technical documentation>`.

Traditional references like

`Writing technical documentation`_

work too but are discouraged. You can link to other pages, like this:

:doc:`Hello World<hello_world>`

or sections within other pages, like this:

:ref:`devs/installation:unstable installation`

We have autosectionlabel enabled so it is not necessary to manually create labels. The depth of sections with automatic labels is set to 2, so the third level of titles will not get automatic labels to avoid duplication.

You can still create labels manually. This way you would ensure links still works when documentation is refactored.

.. _My label:

My Section
==========

:ref:`Link to My Section <My label>`

This link will work across the documentation. Make sure the label is globally unique.

Images¶

The following colours and annotation styles should be used for annotating images. All stroke widths are 3px with a corner radius of 3px. Horizontal underlines are 5px with a corner radius of 2px. The dark green is 39b54a and the light green is d9e021.

Special keywords such as Technical Terminology that the user should be aware of should be bolded, titlecased, and used consistently. You may use italics to emphasize words or phrases. Inline code must be quoted and longer code snippets may use code blocks.

cd /path/to/bonsai
ls

Be sure to specify the language to enable syntax highlighting.

print("Hello, world!")

A button may be used to point users to a critical sample file or download.

Visit critical link

You can use bulleted lists:

Like.
This.

Or ordered lists:

Like.
This.

Note

Instead of writing “Note that XYZ …” you should use notes sparingly to highlight “gotchas”.

Tip

Tips may be used to add a useful but optional suggestion.

Warning

Warnings may be used to highlight common mistakes.

Foo	Bar	Baz
ABC	01	02
DEF	03	04

Building documentation¶

If you want to build the documentation locally, the documentation system uses Sphinx. First, install the theme and theme dependencies:

pip install furo
pip install sphinx-autoapi
pip install sphinx-copybutton

Now you can generate the documentation:

cd /path/to/ifcopenshell/src/bonsai/docs/
make html
cd _build/html
python -m http.server

You will now have a local webserver running hosting the documentation.