Bring in support for mermaid and move pinning forward (ros2#4151)

* Add mermaid support and update pinned version

To get mermaid support working I had to do upgrades. I've updated our pins and documented how they're used as well as how to update them too.

This will allow us to do integrated mermaid sequence diagrams as well as flow diagrams instead of committing images of them.

* clean up docker installation to focus on pip version pinning

* Match folders in ignore too

Signed-off-by: Tully Foote <[email protected]>
Co-authored-by: Tomoya Fujita <[email protected]>

.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