mirror of
https://github.com/IfcOpenShell/IfcOpenShell.git
synced 2026-08-11 18:16:40 +00:00
Dion Moult
89 lines
2.4 KiB
ReStructuredText
89 lines
2.4 KiB
ReStructuredText
Writing docs
|
|
============
|
|
|
|
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.
|
|
|
|
Writing technical documentation
|
|
-------------------------------
|
|
|
|
All documentation is written in ReStructured Text and is available in the
|
|
`BlenderBIM Add-on docs directory
|
|
<https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.7.0/src/blenderbim/docs>`_.
|
|
|
|
You can link to `external websites
|
|
<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_.
|
|
You can also link to sections on the same page, like `Writing technical
|
|
documentation`_. You can link to other pages, like :doc:`Hello
|
|
World<hello_world>` or sections within other pages, like
|
|
:ref:`devs/installation:unstable installation`. We have ``autosectionlabel``
|
|
enabled so it is not necessary to manually create labels.
|
|
|
|
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``.
|
|
|
|
.. image:: documentation-style.png
|
|
|
|
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.
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd /path/to/blenderbim
|
|
$ ls
|
|
|
|
Be sure to specify the language to enable syntax highlighting.
|
|
|
|
.. code-block:: python
|
|
|
|
print("Hello, world!")
|
|
|
|
A button may be used to point users to a critical sample file or
|
|
download.
|
|
|
|
.. container:: blockbutton
|
|
|
|
`Visit critical link <https://blenderbim.org>`__
|
|
|
|
You can use bulleted lists:
|
|
|
|
- Like.
|
|
- This.
|
|
|
|
Or ordered lists:
|
|
|
|
1. Like.
|
|
2. 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.
|
|
|
|
.. seealso::
|
|
|
|
See also blocks should be used to reference `further reading
|
|
<https://blenderbim.org>`__ links.
|
|
|
|
Tables can be very annoying to format. You can use a CSV table instead.
|
|
|
|
.. csv-table::
|
|
:header: "Foo", "Bar", "Baz"
|
|
|
|
"ABC", "01", "02"
|
|
"DEF", "03", "04"
|