mirror of
https://github.com/IfcOpenShell/IfcOpenShell.git
synced 2026-09-11 22:31:55 +00:00
Major documentation refactoring (#4905)
This commit is contained in:
John Yani
@@ -0,0 +1,29 @@
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
BlenderBIM is an open-source project, and its development is driven by the contributions of a dedicated community of developers,
|
||||
architects, engineers, and enthusiasts. If you're interested in contributing to the project, whether by submitting bug reports,
|
||||
suggesting new features, or contributing code, your involvement is highly encouraged and appreciated.
|
||||
|
||||
This part of the documentation covers various aspects of the BlenderBIM development process, including:
|
||||
|
||||
- :doc:`Writing User Documentation </contribute/writing_docs>`
|
||||
- :doc:`Translations and Internationalisation </contribute/translations>`
|
||||
- Contributing Code
|
||||
- :doc:`Installation and Setting up a Development Environment </devs/installation>`
|
||||
- Understanding the Project Structure and Codebase
|
||||
- :doc:`Hello, World! </devs/hello_world>`
|
||||
- :doc:`Undo System </devs/undo_system>`
|
||||
- :doc:`Code Style Guidelines and Best Practices </devs/code_style>`
|
||||
|
||||
..
|
||||
- :doc:`Submitting Pull Requests and Contributing Code </devs/contributing_code>`
|
||||
|
||||
- :doc:`Testing and Quality Assurance </devs/running_tests>`
|
||||
- :doc:`Running Tests </devs/running_tests>`
|
||||
- :doc:`System Support and Multiplatform Compatibility </devs/system_support>`
|
||||
- :doc:`User Experience and User Interface Guidelines </devs/ux_guidelines>`
|
||||
|
||||
The BlenderBIM Developer Documentation is a living resource maintained by the core development team and the open-source community. It serves as a central hub for developers who want to get involved in the project, ensuring a consistent and efficient development process.
|
||||
|
||||
By contributing to BlenderBIM, you'll not only be helping to improve and expand the capabilities of this powerful open-source BIM authoring platform but also be part of a vibrant community driving innovation in the AEC industry.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 2.4 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
@@ -15,7 +15,7 @@ Unstable installation
|
||||
that they are typically updated every day. Simply download a daily build from
|
||||
the `GitHub releases page
|
||||
<https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then follow the
|
||||
usual :doc:`installation instructions</users/installation>`.
|
||||
usual :doc:`installation instructions</users/quickstart/installation>`.
|
||||
|
||||
You will need to choose which build to download.
|
||||
|
||||
|
||||
@@ -1,76 +0,0 @@
|
||||
Translations
|
||||
============
|
||||
|
||||
The BlenderBIM Add-on supports translations to all languages that Blender
|
||||
supports. We'll describe how you can help translate the add-on as a translator,
|
||||
or how you can ensure your strings are translatable as a developer.
|
||||
Translations are managed using a separate add-on built for this purpose.
|
||||
|
||||
1. Clone the `blenderbim-translations
|
||||
<https://github.com/IfcOpenShell/blenderbim-translations>`_ repository. This
|
||||
repository holds all the core translation strings in ``.po`` format.
|
||||
2. Download the `blenderbim-translations add-on
|
||||
<https://github.com/IfcOpenShell/IfcOpenShell/blob/v0.7.0/src/blenderbim/scripts/bbim_translations.py>`_
|
||||
and install it as a Blender add-on. This add-on lets you convert translation
|
||||
data to and from the ``.po`` files to the BlenderBIM Add-on.
|
||||
3. In the **Render Properties** tab, find the **BlenderBIM Translations**
|
||||
panel, and browse to where you have closed the ``blenderbim-translations``
|
||||
repository, and click on **Setup Translation UI**.
|
||||
|
||||
You should now see a new interface with two buttons.
|
||||
|
||||
.. image:: images/translation-panel.png
|
||||
|
||||
How to translate the add-on
|
||||
---------------------------
|
||||
|
||||
Before beginning, look inside the ``blenderbim-translations`` repository for a
|
||||
``.po`` file for the language you want to translate to (e.g. ``de_DE.po`` for
|
||||
German). If this file does not yet exist, congratulations! You are the first
|
||||
person to translate to this language! Create a folder in
|
||||
``blenderbim-translations`` with your language code and copy the
|
||||
``blenderbim.pot`` language template file to that folder and rename it
|
||||
according to your language (e.g. for German you would copy ``blenderbim.pot`` to
|
||||
``de_DE/de_DE.po``).
|
||||
|
||||
Supported language codes are:
|
||||
|
||||
.. code-block::
|
||||
|
||||
'ca_AD', 'en_US', 'es', 'fr_FR', 'ja_JP', 'sk_SK', 'cs_CZ', 'de_DE',
|
||||
'it_IT', 'ka', 'ko_KR', 'pt_BR', 'pt_PT', 'ru_RU', 'uk_UA', 'vi_VN',
|
||||
'zh_HANS', 'zh_HANT', 'ab', 'ar_EG', 'bg_BG', 'el_GR', 'eo', 'eu_EU',
|
||||
'fa_IR', 'fi_FI', 'ha', 'he_IL', 'hi_IN', 'hr_HR', 'hu_HU', 'id_ID',
|
||||
'ky_KG', 'ne_NP', 'nl_NL', 'pl_PL', 'sr_RS', 'sr_RS@latin', 'sv_SE', 'sw',
|
||||
'ta', 'th_TH', 'tr_TR'.
|
||||
|
||||
As a translator, it is recommended to translate text in bulk by modifying the
|
||||
``.po`` files directly. We recommend installing software such as `Poedit
|
||||
<https://poedit.net/>`_. These translation software offer features such as auto
|
||||
translation, suggestions, and tracking. Alternatively, you may edit the ``.po``
|
||||
file as a text file.
|
||||
|
||||
Once you have edited the relevant language's ``.po`` file, click on the
|
||||
**Update Translations From .po** button in the **BlenderBIM Translations**
|
||||
panel.
|
||||
|
||||
How to add new translation strings
|
||||
----------------------------------
|
||||
|
||||
When you have new strings to translate, press the **Parse BlenderBIM strings to
|
||||
.pot** button. This detects strings in the source code using regex patterns and
|
||||
writes out to the ``blenderbim.pot`` language template file. You may then diff
|
||||
this file and propagate changes manually to all translated ``.po`` files.
|
||||
|
||||
The ``.pot`` file is only used as a blank template for users to create or
|
||||
compare ``.po`` files. The ``.po`` files are the source of truth for
|
||||
translation strings. Blender does not read from the ``.pot`` or ``.po`` files.
|
||||
Instead, Blender reads from ``blenderbim/translations.py`` which contains a
|
||||
dictionary of strings formatted specifically for Blender. The
|
||||
``translations.py`` file is generated from the ``.po`` files. This is generated
|
||||
when we distribute installable packages, or when translators manually press the
|
||||
**Update Translations From .po** button.
|
||||
|
||||
.. warning::
|
||||
|
||||
Do not commit the ``translations.py`` file as it is auto-generated.
|
||||
@@ -1,119 +0,0 @@
|
||||
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 press the edit button on the top right on any documentation page to
|
||||
quickly edit their content.
|
||||
|
||||
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:`devs/writing_docs:Writing technical
|
||||
documentation` or with :ref:`custom text<devs/writing_docs:writing technical
|
||||
documentation>`. Traditional references like `Writing technical documentation`_
|
||||
work too but are discouraged. 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 depth of sections
|
||||
with automatic labels is set to 2, so the third level of titles
|
||||
will not get automatic labels to avoid duplication.
|
||||
|
||||
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:: images/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"
|
||||
|
||||
Building documentation
|
||||
----------------------
|
||||
|
||||
If you want to build the documentation locally, the documentation system uses
|
||||
`Sphinx <https://www.sphinx-doc.org/en/master/>`_. First, install the theme and
|
||||
theme dependencies:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install furo
|
||||
$ pip install sphinx-autoapi
|
||||
$ pip install sphinx-copybutton
|
||||
|
||||
Now you can generate the documentation:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd /path/to/ifcopenshell/src/blenderbim/docs/
|
||||
$ make html
|
||||
$ cd _build/html
|
||||
$ python -m http.server
|
||||
|
||||
You will now have a local webserver running hosting the documentation.
|
||||
Reference in New Issue
Block a user