Merge branch 'iblrigv8dev' of github.com:int-brain-lab/iblrig into ib…

…lrigv8dev

docs/source/conf.py

@@ -1,13 +1,7 @@
 from datetime import date
 
-try:
-    from iblrig import __version__
-except ModuleNotFoundError:
-    import sys
-    from pathlib import Path
-    _BASE_DIR = Path(__file__).resolve().parents[2]
-    sys.path.append(str(_BASE_DIR))
-    from iblrig import __version__
+from iblrig import __version__
+from iblrig.constants import BASE_PATH
 
 project = 'iblrig'
 copyright = f'2018 – {date.today().year} International Brain Laboratory'
@@ -18,7 +12,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel']
+extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel', 'sphinx_simplepdf']
 autosectionlabel_prefix_document = True
 source_suffix = ['.rst', '.md']
 
@@ -31,3 +25,17 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+
+
+simplepdf_vars = {
+    'primary': '#FA2323',
+    'secondary': '#379683',
+    'cover': 'white',
+    'cover-bg': 'linear-gradient(180deg, rgb(0, 81, 142) 0%, rgb(0, 158, 214) 50%, rgb(201, 53, 154) 100%)',
+}
+simplepdf_file_name = f'iblrig_{__version__}_reference.pdf'
+simplepdf_weasyprint_flags = ['-j70', '-D150', '--hinting']
+html_context = {
+    'docs_scope': 'external',
+    'cover_meta_data': 'International Brain Laboratory',
+}

docs/source/index.rst

@@ -1,15 +1,10 @@
-.. only:: html
+.. if-builder:: html
 
    .. include:: ../../README.md
       :parser: myst_parser.sphinx_
 
-.. only:: latex
-
-   Welcome to IBLRIG
-   =================
-
 .. toctree::
-   :caption: Contents:
+   :maxdepth: 3
    :hidden:
 
    installation
@@ -19,7 +14,7 @@
    reference_developer_guide
    faq
 
-.. only:: html
+.. if-builder:: html
 
    .. toctree::
       :hidden:

docs/source/installation.rst

@@ -49,8 +49,8 @@ Now, run the following command at the prompt of Windows PowerShell:
    and usability.
 
 
-Installing MS Visual C++ Redistributable
-----------------------------------------
+Installing Visual C++ Redistributable
+-------------------------------------
 
 With the Administrator PowerShell still open, run the following commands:
 
@@ -67,7 +67,7 @@ With the Administrator PowerShell still open, run the following commands:
 .. admonition:: Background
    :class: seealso
 
-   These commands will create a temporary directory, download and silently install the Visual C++ Redistributable package for
+   These commands will create a temporary directory, download and install the Visual C++ Redistributable package for
    64-bit Windows systems. The installer is retrieved from a Microsoft server and executed with parameters to ensure a seamless
    and unobtrusive installation process.
 

docs/source/reference_developer_guide.rst

@@ -5,7 +5,7 @@ Developer Guide
 Versioning Scheme
 -----------------
 
-IBLRIG v8 uses `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`_.
+IBLRIG v8 uses `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 Its version string (currently "|version|") is a combination of three fields, separated by dots:
 
 .. centered:: ``MAJOR`` . ``MINOR`` . ``PATCH``
@@ -32,18 +32,21 @@ Here,
 * ``post3`` indicates the third unversioned commit after the latest versioned release, and
 * ``dirty`` indicates the presence of uncommited changes in your local repository of IBLRIG.
 
-Both of these fields are inferred by means of git describe and do not require manual interaction from the developer.
+Both of these fields are automatically inferred (by means of ``git describe``) and do not require manual interaction from the
+developer.
 
 
-PDM
----
+Package Management and Development Workflows with PDM
+-----------------------------------------------------
 
 We use `PDM <https://pdm-project.org/en/latest/>`_ to manage dependencies of IBLRIG.
-See `PDM's documentation <https://pdm-project.org/en/latest/#installation>` for help with installing PDM.
+PDM can also be used to run various commands with relevance to the development process without having to activate a virtual
+environment first.
+Please refer to `PDM's documentation <https://pdm-project.org/en/latest/#installation>`_ for help with installing PDM.
 
 
 Installing Developer Dependencies
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To install additional dependencies needed for working on IBLRIG's code-base, run:
 
@@ -52,45 +55,39 @@ To install additional dependencies needed for working on IBLRIG's code-base, run
    pdm sync -d
 
 
-Running Unit Tests Locally
---------------------------
+Running Unit Tests
+^^^^^^^^^^^^^^^^^^
 
 To run unit tests locally, run:
 
 .. code-block:: console
 
    pdm run pytest
 
-This will also generate a coverage report which can be found in the ``htmlcov`` directory.
+This will also generate a HTML based coverage report which can be found in the ``htmlcov`` directory.
 
 
 Linting & Formatting
---------------------
-
-To lint your code, run the:
-
-.. code-block:: console
+^^^^^^^^^^^^^^^^^^^^
 
-   pdm run ruff check
+We use `Ruff <https://docs.astral.sh/ruff>`_ for linting and formatting our code-base in close accordance with `the Black code
+style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
 
-Adding the commandline flag ``--fix`` will automatically fix issues that are deemed safe to handle:
+To lint your code, run:
 
 .. code-block:: console
 
-   pdm run ruff check --fix
-
-To *check* if your code conforms to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_, run:
-
-.. code-block:: console
+   pdm run ruff check
 
-   pdm run ruff format --check
+Appending the flag ``--fix`` to the above command will automatically fix issues that are deemed safe to handle.
 
-To reformat your code according to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_, run:
+To reformat your code according to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_ run:
 
 .. code-block:: console
 
    pdm run ruff format
 
+Appending the flag ``--check`` to the above command will check your code for formatting issues without applying any changes.
 Refer to `Ruff Formater's documentation <https://docs.astral.sh/ruff/formatter/>`_ for further details.
 
 
@@ -115,18 +112,29 @@ Release Checklist
 Building the documentation
 --------------------------
 
+To build the documentation, run:
+
 .. code-block:: console
 
    pdm run sphinx-autobuild ./docs/source ./docs/build
 
+You can also export the documentation to a PDF file:
+
+.. code-block:: console
+
+   pdm run make -C docs/ simplepdf
+
+Find the exported PDF file in ``docs/build/simplepdf``.
+
 
 Contribute to the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 To write the documentation:
 
 * Write the documentation in the ``iblrig/docs/source`` folder
 * If you are writing in a new file, add it to the ``index.rst`` so it appears in the table of content
-* Push all your changes to the ``iblrigv8dev`` branch ; if this branch does not exist, create it first
+* Push all your changes to the ``iblrigv8dev`` branch; if this branch does not exist, create it first
 
 To release the documentation onto the `website <https://int-brain-lab.github.io/iblrig>`_: