Rename source dir

src/bonsai/docs/contribute/translations.rst

@@ -0,0 +1,76 @@
+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.8.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.

src/bonsai/docs/contribute/writing_docs.rst

@@ -0,0 +1,167 @@
+Contribute to this Manual
+=========================
+
+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.8.0/src/blenderbim/docs>`_.
+You can press the edit button on the top right on any documentation page to
+quickly edit their content.
+
+Links
+^^^^^
+
+You can link to
+
+.. code-block:: restructuredtext
+
+  `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
+
+.. code-block:: restructuredtext
+
+  :ref:`contribute/writing_docs:Writing technical documentation`
+  
+or with
+
+.. code-block:: restructuredtext
+
+  :ref:`custom text<contribute/writing_docs:writing technical documentation>`.
+  
+Traditional references like 
+  
+.. code-block:: restructuredtext
+ 
+  `Writing technical documentation`_
+
+work too but are discouraged. You can link to other pages, like this:
+
+.. code-block:: restructuredtext
+
+  :doc:`Hello World<hello_world>`
+
+or sections within other pages, like this:
+
+.. code-block:: restructuredtext
+
+  :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.
+
+.. code-block:: restructuredtext
+
+    .. _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``.
+
+.. 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:: bash
+
+    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:: bash
+
+    pip install furo
+    pip install sphinx-autoapi
+    pip install sphinx-copybutton
+
+Now you can generate the documentation:
+
+.. code-block:: bash
+
+    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.