From eae542f90f45752d31923172d8e5deb1a7b2c233 Mon Sep 17 00:00:00 2001
From: Dion Moult <dion@thinkmoult.com>
Date: Sat, 30 Mar 2024 17:37:14 +1100
Subject: [PATCH] Fix #4461. Write documentation on how to build and edit
 documentation.

---
 src/blenderbim/docs/devs/writing_docs.rst     | 26 ++++++++++
 src/ifcopenshell-python/docs/introduction.rst |  1 +
 .../docs/introduction/how_to_contribute.rst   | 49 +++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 src/ifcopenshell-python/docs/introduction/how_to_contribute.rst

diff --git a/src/blenderbim/docs/devs/writing_docs.rst b/src/blenderbim/docs/devs/writing_docs.rst
index b40bccf4a3..f888b398da 100644
--- a/src/blenderbim/docs/devs/writing_docs.rst
+++ b/src/blenderbim/docs/devs/writing_docs.rst
@@ -12,6 +12,8 @@ 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>`_.
@@ -86,3 +88,27 @@ Tables can be very annoying to format. You can use a CSV table instead.
 
     "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.
diff --git a/src/ifcopenshell-python/docs/introduction.rst b/src/ifcopenshell-python/docs/introduction.rst
index b4661218ed..d3c847fa86 100644
--- a/src/ifcopenshell-python/docs/introduction.rst
+++ b/src/ifcopenshell-python/docs/introduction.rst
@@ -87,3 +87,4 @@ IfcOpenShell is a modular ecosystem of tools that work together, where each tool
 
    introduction/introduction_to_bim
    introduction/introduction_to_ifc
+   introduction/how_to_contribute
diff --git a/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst b/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst
new file mode 100644
index 0000000000..59015fe339
--- /dev/null
+++ b/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst
@@ -0,0 +1,49 @@
+How to contribute
+=================
+
+IfcOpenShell is made possible by the contributions of hundreds of people.
+Contributions range from developing code, writing documentation, creating
+tutorials, responding to requests, reporting bugs, and marketing.
+
+Writing documentation
+---------------------
+
+A great way to contribute without writing code is to help writing
+documentation.
+
+All documentation is written in ReStructured Text and is available in the
+`IfcOpenShell docs directory
+<https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.7.0/src/ifcopenshell-python/docs>`_.
+You can press the edit button on the top right on any documentation page to
+quickly edit their content.
+
+Python API documentation is autogenerated from docstrings present in the source
+code of the respective Python module.
+
+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/ifcopenshell-python/docs/
+    $ make html
+    $ cd _build/html
+    $ python -m http.server
+
+You will now have a local webserver running hosting the documentation.
+
+.. tip::
+   
+   It may take some time to generate the API documentation. You can edit the
+   `list of autoapi directories
+   <https://github.com/IfcOpenShell/IfcOpenShell/blob/v0.7.0/src/ifcopenshell-python/docs/conf.py#L69>`_
+   to make this faster