Merge pull request #2975 from jessica-mitchell/add-plantuml-docs

Add plantuml to docs

Author: jessica-mitchell

.readthedocs.yml

@@ -3,12 +3,17 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
-
+    python: "3.10"
+  apt_packages:
+    - default-jre-headless
+  jobs:
+    pre_install:
+      - wget "https://github.com/plantuml/plantuml/releases/download/v1.2023.10/plantuml.jar" -O "/tmp/plantuml.jar"
+      - echo "ee06454723028763dd8280459e8fd8f31fcd85b1ae8d9ab0e32122243c098c3b" "/tmp/plantuml.jar" | sha256sum -c
 sphinx:
   builder: html
   configuration: doc/htmldoc/conf.py
 
 python:
-   install:
-   - requirements: doc/requirements.txt
+  install:
+    - requirements: doc/requirements.txt

doc/htmldoc/conf.py

@@ -53,6 +53,7 @@
     "sphinx.ext.intersphinx",
     "sphinxcontrib.mermaid",
     "sphinx.ext.mathjax",
+    "sphinxcontrib.plantuml",
     "add_button_notebook",
     "IPython.sphinxext.ipython_console_highlighting",
     "nbsphinx",
@@ -70,6 +71,8 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["templates"]
 
+# To run plantuml locally see the user documentation workflow
+plantuml = "java -jar /tmp/plantuml.jar"
 sphinx_gallery_conf = {
     # path to your examples scripts
     "examples_dirs": "../../pynest/examples",

doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst

@@ -118,6 +118,21 @@ If you use pip, install ``pandoc`` from your platform's package manager (e.g. ap
 
     sudo apt-get install pandoc
 
+.. admonition::  Building plantuml diagrams locally
+
+   The plantuml diagrams require additional requirements
+   to make them work in a local build.
+
+   You will need to
+
+   - check if you have Java installed. The minimum version needed is Java 8.
+     (e.g., to install the latest available version on Ubuntu: ``apt install jre-default``)
+   - Download the `plantuml jar file <https://plantuml.com/download>`_ (Minimum version is 1-2023-10)
+   - Move the jar file to ``/tmp/plantuml.jar``
+
+   - To see if plantuml diagrams render correctly after building the documentation you can take a look
+     at our :ref:`test_uml`.
+
 
 Edit and create pages
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -176,6 +191,7 @@ you will need to build the documentation locally with Sphinx.
 
    sphinx-build . ../_build/html -b html
 
+
 #. Preview files. They are located in ``doc/_build/html``
 
 .. code-block:: bash
@@ -229,3 +245,8 @@ on Read the Docs, you can set up your own account and link it with your Github a
 
 See `this guide <https://docs.readthedocs.io/en/stable/intro/import-guide.htmli>`_
 for more information.
+
+.. toctree::
+   :hidden:
+
+   /testuml

doc/htmldoc/testuml.rst

@@ -0,0 +1,25 @@
+.. _test_uml:
+
+Test uml page
+-------------
+
+Two diagrams should render on this page.
+
+**Basic example:**
+
+
+.. uml::
+
+   Alice -> Bob: Hi!
+   Alice <- Bob: How are you?
+
+
+**C4 example:**
+
+
+.. uml::
+
+ !include <C4/C4_Context>
+ !define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5
+ !include FONTAWESOME/users.puml
+ Person(user, "C4 fans", "Hello to Sphinx!", $sprite="users")

doc/requirements.txt

@@ -1,37 +1,37 @@
-Image==1.5.30
+Image>=1.5.30
 PyYAML>=4.2b1
-RestrictedPython==6.2
-cmake==3.26.0
-csvkit==1.1.1
+RestrictedPython>=6.2
+cmake>=3.26.0
+csvkit>=1.1.1
 cython>=0.29.14
-docutils==0.19
-example==0.1.0
-flask==2.3.2
-flask_cors==3.0.10
-ipykernel==6.22.0
-# Pin ipython to a version compatible with Python 3.8, the latest supported by RTD
-ipython~=8.11.0
-jupyter==1.0.0
-matplotlib==3.7.1
-mock==5.0.2
-nbsphinx==0.9.1
-numpy==1.22.0
-numpydoc==1.5.0
-pandoc==2.3.0
-path.py==12.5.0
-pydot==1.4.2
-pytest==7.3.1
-recommonmark==0.7.1
-scipy==1.10.1
-seaborn==0.12.2
-sphinx==6.2.1
-sphinx_autobuild==2021.3.14
+docutils>=0.19
+example>=0.1.0
+flask>=2.3.2
+flask_cors>=3.0.10
+ipykernel>=6.22.0
+ipython>=8.11.0
+jupyter>=1.0.0
+matplotlib>=3.7.1
+mock>=5.0.2
+nbsphinx>=0.9.1
+numpy>=1.22.0
+numpydoc>=1.5.0
+pandoc>=2.3.0
+path.py>=12.5.0
+pydot>=1.4.2
+pytest>=7.3.1
+recommonmark>=0.7.1
+scipy>=1.10.1
+seaborn>=0.12.2
+sphinx>=6.2.1
+sphinx_autobuild>=2021.3.14
 sphinx-copybutton>=0.5.2
 sphinx-notfound-page>=0.8.3
-sphinx-design==0.4.1
-sphinx-gallery==0.13.0
-sphinx-material==0.0.35
-sphinxcontrib-mermaid
-statsmodels==0.13.5
-tqdm==4.65.0
-yamllint==1.31.0
+sphinx-design>=0.4.1
+sphinx-gallery>=0.13.0
+sphinx-material>=0.0.35
+sphinxcontrib-mermaid>=0.9.2
+sphinxcontrib-plantuml>=0.26
+statsmodels>=0.13.5
+tqdm>=4.65.0
+yamllint>=1.31.0