From c569b503aa340dd140e77dbd9fb05f99a69784cf Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 5 Feb 2024 08:08:30 -0800 Subject: [PATCH] Bring in support for mermaid and move pinning forward (#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 Co-authored-by: Tomoya Fujita --- .gitignore | 2 +- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ conf.py | 1 + constraints.txt | 34 ++++++++++++++++------------------ docker/image/Dockerfile | 8 +------- requirements.txt | 13 +++++++------ 6 files changed, 66 insertions(+), 32 deletions(-) diff --git a/.gitignore b/.gitignore index 0499adb29a1..9878dcbb35f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ build/ -plugins/__pycache__ _build/ .idea/ .vscode/ +__pycache__ diff --git a/README.md b/README.md index b427435d8f0..86ba153b968 100644 --- a/README.md +++ b/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. diff --git a/conf.py b/conf.py index f6f0a05435e..3b099d675f1 100644 --- a/conf.py +++ b/conf.py @@ -83,6 +83,7 @@ 'sphinx_tabs.tabs', 'sphinx_rtd_theme', 'sphinx_sitemap_ros', + 'sphinxcontrib.mermaid', ] # Intersphinx mapping diff --git a/constraints.txt b/constraints.txt index 43a5e18dcdb..79362faefda 100644 --- a/constraints.txt +++ b/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 diff --git a/docker/image/Dockerfile b/docker/image/Dockerfile index 326ff7bb755..000de1825e9 100644 --- a/docker/image/Dockerfile +++ b/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 diff --git a/requirements.txt b/requirements.txt index 69607aa7835..c7a3309e0e7 100644 --- a/requirements.txt +++ b/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