From 58d0e9651b494cfbe79508a2c26f25e742b67d8d Mon Sep 17 00:00:00 2001
From: David Douard <david.douard@sdfa3.org>
Date: Wed, 15 Nov 2023 14:48:17 +0100
Subject: [PATCH] Add a hook to ensure README files are symlinked in
swh-xxx/docs/
The idea is to generalize the fact that all the swh packages should have
a README file in the root directory, but this should be included in the
sphinx documentation, for which the simplest way is to make the file
symlinked in docs/. For several reasons, it's simpler to make this
symlink creation handled by a hook/automation script at doc build time
rather than add the symlink in the git repo of the swh package.
---
.gitignore | 1 +
docs/devel/bin/ln-sphinx-subprojects | 14 +++++++++++---
docs/index.rst | 1 +
swh/docs/sphinx/conf.py | 23 +++++++++++++++++++++--
4 files changed, 34 insertions(+), 5 deletions(-)
mode change 100755 => 100644 swh/docs/sphinx/conf.py
diff --git a/.gitignore b/.gitignore
index b81336c6..130bd561 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ build/
/swh/docs/sphinx/__pycache__/
/version.txt
apidoc/
+docs/README.*
diff --git a/docs/devel/bin/ln-sphinx-subprojects b/docs/devel/bin/ln-sphinx-subprojects
index edd5d6f3..512b04c1 100755
--- a/docs/devel/bin/ln-sphinx-subprojects
+++ b/docs/devel/bin/ln-sphinx-subprojects
@@ -4,9 +4,9 @@ set -e
create_links () {
mkdir -p sources
for pymodule in $(cd ../../../ && bin/ls-py-modules) ; do
- if [ "$pymodule" = 'swh-docs' ] ; then
- continue
- fi
+ case "$pymodule" in
+ "swh-docs"|"swh-icinga-plugins") continue;;
+ esac
if [ ! -e "$pymodule" -a -d "../../../${pymodule}/docs" ] ; then
ln -s "../../../${pymodule}/docs" "$pymodule"
fi
@@ -16,6 +16,14 @@ create_links () {
if [ -d "../../../${pymodule}/swh" ] ; then
cp -r -f --symbolic-link $(realpath ../../../${pymodule}/swh/*) sources/swh/
fi
+ pushd ../../../${pymodule}
+ for EXT in rst md; do
+ if [ -f README.$EXT -a ! -f docs/README.$EXT ] ; then
+ ln -s ../README.$EXT docs
+ break
+ fi
+ done
+ popd
done
}
diff --git a/docs/index.rst b/docs/index.rst
index ac556989..af7ff6ff 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -438,3 +438,4 @@ Table of contents
devel/api-reference
user/index
sysadm/index
+ About this documentation project <README>
diff --git a/swh/docs/sphinx/conf.py b/swh/docs/sphinx/conf.py
old mode 100755
new mode 100644
index 0e798647..e14a26bf
--- a/swh/docs/sphinx/conf.py
+++ b/swh/docs/sphinx/conf.py
@@ -85,8 +85,7 @@ language = "en"
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = [
"_build",
- "**swh-icinga-plugins/index.rst",
- "**swh.loader.cvs.rcsparse.setup.rst",
+ "**swh-icinga-plugins/*.rst",
"**/swh/lister/maven/README.md",
"**/swh/loader/cvs/cvs2gitdump/README.md",
"**/swh/web/tests/resources/contents/code/extensions/test.md",
@@ -331,7 +330,27 @@ def get_sphinx_warning_handler():
return handler
+# before starting building the doc, we want to ensure all the
+# swh-xxx/docs/README.{rst,md} exists, or create a symlink if not. This is only
+# useful when building the documentation of a sw package in isolation; when
+# building the whole swh-docs, then the docs/devel/bin/ln-sphinx-subprojects
+# will take care of these symlinks
+def ensure_readme(app, config):
+ srcpath = app.srcdir
+ if srcpath.name.endswith("swh.docs"):
+ # ln-sphinx-subprojects script should already have done the job
+ return
+ for extension in ("rst", "md"):
+ fname = f"README.{extension}"
+ readme_file = srcpath / ".." / fname
+ symlink = srcpath / fname
+ if readme_file.exists() and not symlink.exists():
+ symlink.symlink_to(readme_file)
+ break
+
+
def setup(app):
+ app.connect("config-inited", ensure_readme)
# env-purge-doc event is fired before source-read
app.connect("env-purge-doc", set_django_settings)
# add autosimple directive (used in swh-web)
--
GitLab