From 0c0b5b599b1471b340b7ad574ae6411b0ff07b56 Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Tue, 30 Jan 2024 11:09:50 -0800 Subject: [PATCH] Add mermain support and update pinned version To get mermaide 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. --- .gitignore | 1 + README.md | 39 +++++++++++++++++++++++++++++++++++++++ conf.py | 1 + constraints.txt | 34 ++++++++++++++++------------------ requirements.txt | 13 +++++++------ 5 files changed, 64 insertions(+), 24 deletions(-) diff --git a/.gitignore b/.gitignore index 0499adb29a1..9109e65fc14 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ plugins/__pycache__ _build/ .idea/ .vscode/ +__pycache__ diff --git a/README.md b/README.md index b427435d8f0..eaa79cda8e0 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,42 @@ 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/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