Bring in support for mermaid and move pinning forward

.gitignore

@@ -1,5 +1,5 @@
 build/
-plugins/__pycache__
 _build/
 .idea/
 .vscode/
+__pycache__

README.md

@@ -11,3 +11,43 @@ Please see the [Contributing to ROS 2 Documentation](https://docs.ros.org/en/rol
 ## Contributing to ROS 2
 
 To contribute to the ROS 2 source code project please refer to the [ROS 2 contributing guidelines](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing.html).
+
+## Prerequisites
+
+To build this you need to install
+
+* make
+* graphviz
+* python virtualenv
+
+
+In the virtualenv 
+
+```
+pip install -r requirements.txt -c constraints.txt
+```
+
+### Pinned versions
+
+For development we currently use Jammy as our build platform.
+And all python versions are pinned in the constraints file to make sure that things are reproducible.
+To upgrade the system validate that things are working and then use `pip freeze > constraints.txt` to lock in the versions to upgrade.
+
+## Building HTML
+
+### Local development test
+For local testing of the current tree use:
+
+`make html`
+
+`sensible-browser build/html/index.html`
+
+### Deployment test
+
+To test building the multisite version deployed to the website use:
+
+`make multiversion`
+
+`sensible-browser build/html/rolling/index.html`
+
+**NB:** This will ignore local workspace changes and build from the branches.

conf.py

@@ -83,6 +83,7 @@
     'sphinx_tabs.tabs',
     'sphinx_rtd_theme',
     'sphinx_sitemap_ros',
+    'sphinxcontrib.mermaid',
 ]
 
 # Intersphinx mapping

constraints.txt

@@ -1,35 +1,33 @@
-Jinja2==3.0.3
-MarkupSafe==2.0.1
-Pygments==2.11.2
 alabaster==0.7.12
-babel==2.8.0
+Babel==2.14.0
 certifi==2020.6.20
 chardet==4.0.0
+doc8==1.1.1
+docutils==0.20.1
+idna==2.10
 imagesize==1.3.0
-importlib-metadata==4.6.4
-more-itertools==8.10.0
+Jinja2==3.0.3
+MarkupSafe==2.0.1
 packaging==21.3
 pbr==5.8.0
-pip==22.0.2
+Pygments==2.17.2
 pyparsing==2.4.7
 pytz==2022.1
 requests==2.25.1
-restructuredtext-lint==1.3.2
-roman==3.3
-setuptools==59.6.0
-six==1.16.0
+restructuredtext_lint==1.3.2
 snowballstemmer==2.2.0
-Sphinx==4.3.2
-sphinx-copybutton==0.4.0
+Sphinx==7.2.6
+sphinx-copybutton==0.5.2
 sphinx-multiversion==0.2.4
-sphinx-rtd-theme==1.0.0
-sphinx-tabs==3.2.0
+sphinx-rtd-theme==2.0.0
+sphinx-tabs==3.4.5
 sphinxcontrib-applehelp==1.0.4
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-mermaid==0.9.2
 sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.10
 stevedore==3.5.0
 urllib3==1.26.5
-wheel==0.37.1
-zipp==1.0.0

docker/image/Dockerfile

@@ -16,13 +16,7 @@ RUN apt-get update && \
         git-all \
         graphviz \
         make \
-        python3-doc8 \
-        python3-docutils \
-        python3-pip \
-        python3-sphinx \
-        python3-sphinx-copybutton \
-        python3-sphinx-rtd-theme \
-        python3-sphinx-tabs && \
+        python3-pip && \
     rm -rf /var/lib/apt/lists/*
 
 RUN useradd -u $uid -m $user

requirements.txt

@@ -1,8 +1,9 @@
 doc8
 docutils
-pip==22.0.2
-sphinx==4.3.2
-sphinx-copybutton==0.4.0
-sphinx-multiversion==0.2.4
-sphinx-rtd-theme==1.0.0
-sphinx-tabs==3.2.0
+pip
+sphinx
+sphinx-copybutton
+sphinx-multiversion
+sphinx-rtd-theme
+sphinx-tabs
+sphinxcontrib-mermaid