Enable Sphinx auto section labels. Minor doc link fix.

src/blenderbim/docs/conf.py

@@ -48,7 +48,10 @@ release = "0.0.220504"
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosectionlabel"]
+
+# Auto add document prefixes to help guarantee uniqueness of automatic section references.
+autosectionlabel_prefix_document = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

src/blenderbim/docs/devs/writing_docs.rst

@@ -13,10 +13,13 @@ 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://ifcopenshell.org>`_. You can also
+You can link to `external websites
-link to sections on the same page, like `Writing technical documentation`_.
+<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
-:doc:`Code examples<code_examples>`
+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

src/blenderbim/docs/users/installation.rst

@@ -133,11 +133,10 @@ FAQ
 1. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.7'"**
 
    Check which BlenderBIM Add-on build you are using. The zip will have either
-   ``py37``, ``py39``, or ``py310`` in the name. See the instructions in the
+   ``py39`` or ``py310`` in the name. If you are using a Mac, also make sure
-   `Unstable installation <../devs/installation.html#unstable-installation>`__ section to check that you have installed the
+   you are using the M1 version if you have a newer Mac. See the instructions
-   correct version.
+   in the :ref:`devs/installation:unstable installation` section to check that
-
+   you have installed the correct version.
-
 
 2. **I am on Ubuntu and get an error similar to "ImportError:
    /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"**

src/ifcopenshell-python/docs/conf.py

@@ -54,7 +54,10 @@ release = "0.7.0"
 # - No subnav making it really hard to navigate
 # - Kinda hacky setup https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough
 # - I couldn't customise the template to show submodules above members which makes API discovery hard for users
-extensions = ["autoapi.extension"]
+extensions = ["autoapi.extension", "sphinx.ext.autosectionlabel"]
+
+# Auto add document prefixes to help guarantee uniqueness of automatic section references.
+autosectionlabel_prefix_document = True
 
 # We'll add the toctree entry ourselves to distinguish between C++ and Python
 autoapi_add_toctree_entry = True