From 87e1e13f2df429b49299a220ea20d836e392c943 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Fri, 13 Oct 2023 21:16:27 +0200 Subject: [PATCH 1/6] opt permission denied using tmp --- .readthedocs.yml | 13 +++++++++---- doc/htmldoc/conf.py | 1 + 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index dd5b39156b..744628c8e7 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/doc/htmldoc/conf.py b/doc/htmldoc/conf.py index fbc0ba0b0a..60dce6450f 100644 --- a/doc/htmldoc/conf.py +++ b/doc/htmldoc/conf.py @@ -70,6 +70,7 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["templates"] +plantuml = "java -jar /tmp/plantuml.jar" sphinx_gallery_conf = { # path to your examples scripts "examples_dirs": "../../pynest/examples", From ef281223d909dd9bfb0f9c7e4897acf23f2b4ae5 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Fri, 13 Oct 2023 22:32:55 +0200 Subject: [PATCH 2/6] add note about running plantuml locally --- doc/htmldoc/conf.py | 1 + .../user_documentation_workflow.rst | 13 +++++++++++++ 2 files changed, 14 insertions(+) diff --git a/doc/htmldoc/conf.py b/doc/htmldoc/conf.py index 60dce6450f..41ebcee313 100644 --- a/doc/htmldoc/conf.py +++ b/doc/htmldoc/conf.py @@ -70,6 +70,7 @@ # 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 diff --git a/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst b/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst index 1b01b91fab..be757b369f 100644 --- a/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst +++ b/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst @@ -118,6 +118,18 @@ 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 `_ (Minimum version is 1-2023-10) + - Move the jar file to ``/tmp/plantuml.jar`` + Edit and create pages ~~~~~~~~~~~~~~~~~~~~~~ @@ -176,6 +188,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 From 66cf6998460db03a8bb275e0aa056972d85293b6 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Fri, 13 Oct 2023 22:50:04 +0200 Subject: [PATCH 3/6] add test page for umls --- doc/htmldoc/testuml.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 doc/htmldoc/testuml.rst diff --git a/doc/htmldoc/testuml.rst b/doc/htmldoc/testuml.rst new file mode 100644 index 0000000000..6a6559f1d9 --- /dev/null +++ b/doc/htmldoc/testuml.rst @@ -0,0 +1,17 @@ +:orphan: + +Test page +--------- + +.. uml:: + + Alice -> Bob: Hi! + Alice <- Bob: How are you? + + +.. uml:: + + !include + !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") From 39462942979d7407219b993171f866dad6c0354a Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Fri, 13 Oct 2023 22:51:34 +0200 Subject: [PATCH 4/6] add sphinx plantuml to ext and req, update req to >= --- doc/htmldoc/conf.py | 1 + doc/requirements.txt | 66 ++++++++++++++++++++++---------------------- 2 files changed, 34 insertions(+), 33 deletions(-) diff --git a/doc/htmldoc/conf.py b/doc/htmldoc/conf.py index 41ebcee313..ee81b4a2f5 100644 --- a/doc/htmldoc/conf.py +++ b/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", diff --git a/doc/requirements.txt b/doc/requirements.txt index 9c374d6875..e1defe964f 100644 --- a/doc/requirements.txt +++ b/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-plantum>=0.26 +statsmodels>=0.13.5 +tqdm>=4.65.0 +yamllint>=1.31.0 From 09b8faad4ab22f4b146ba7070dc7d16cb4c22714 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Fri, 13 Oct 2023 23:07:55 +0200 Subject: [PATCH 5/6] fix typo --- doc/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index e1defe964f..b41e49ad1f 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -31,7 +31,7 @@ sphinx-design>=0.4.1 sphinx-gallery>=0.13.0 sphinx-material>=0.0.35 sphinxcontrib-mermaid>=0.9.2 -sphinxcontrib-plantum>=0.26 +sphinxcontrib-plantuml>=0.26 statsmodels>=0.13.5 tqdm>=4.65.0 yamllint>=1.31.0 From 4a73806734ec12c77e51b61cc920b112a534bb8e Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 13 Nov 2023 20:57:52 +0100 Subject: [PATCH 6/6] add suggestions to link test page to workflow docs --- .../user_documentation_workflow.rst | 8 ++++++++ doc/htmldoc/testuml.rst | 14 +++++++++++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst b/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst index be757b369f..d8d40f612f 100644 --- a/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst +++ b/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst @@ -130,6 +130,9 @@ If you use pip, install ``pandoc`` from your platform's package manager (e.g. ap - Download the `plantuml jar file `_ (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 ~~~~~~~~~~~~~~~~~~~~~~ @@ -242,3 +245,8 @@ on Read the Docs, you can set up your own account and link it with your Github a See `this guide `_ for more information. + +.. toctree:: + :hidden: + + /testuml diff --git a/doc/htmldoc/testuml.rst b/doc/htmldoc/testuml.rst index 6a6559f1d9..edfbce3d27 100644 --- a/doc/htmldoc/testuml.rst +++ b/doc/htmldoc/testuml.rst @@ -1,7 +1,12 @@ -:orphan: +.. _test_uml: + +Test uml page +------------- + +Two diagrams should render on this page. + +**Basic example:** -Test page ---------- .. uml:: @@ -9,6 +14,9 @@ Test page Alice <- Bob: How are you? +**C4 example:** + + .. uml:: !include