From c5a2a6e4959b9a459fcb7c1928618c256cf3f532 Mon Sep 17 00:00:00 2001 From: Youen Date: Wed, 17 May 2023 20:25:31 +0200 Subject: [PATCH 1/5] Configuration de sphinx-multiversion Installation : pip install sphinx-multiversion Utilisation : make html_versions --- .gitignore | 1 + Makefile | 6 +++++- source/_templates/versions.html | 27 +++++++++++++++++++++++++++ source/conf.py | 28 ++++++++++++++++++++-------- source/exts/rtd_current_version.py | 14 ++++++++++++++ 5 files changed, 67 insertions(+), 9 deletions(-) create mode 100644 source/_templates/versions.html create mode 100644 source/exts/rtd_current_version.py diff --git a/.gitignore b/.gitignore index 9553705..02432eb 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ /.metadata/ /_local/ +*.pyc diff --git a/Makefile b/Makefile index a17aca5..88a6fd1 100644 --- a/Makefile +++ b/Makefile @@ -22,8 +22,12 @@ help: # We clear the html folder before rebuilding, otherwise some things are # not updated (like static files) html: - rm -rf "$(BUILDDIR)/html/*" + rm -rf $(BUILDDIR)/html/* @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +html_versions: + rm -rf $(BUILDDIR)/html_versions/* + sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html_versions" $(SPHINXOPTS) $(O) + pdf: weasyprint python3 sphinx-tools/make_pdf.py "$(SOURCEDIR)" "$(BUILDDIR)" diff --git a/source/_templates/versions.html b/source/_templates/versions.html new file mode 100644 index 0000000..fb3355f --- /dev/null +++ b/source/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Autres versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Versions
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} \ No newline at end of file diff --git a/source/conf.py b/source/conf.py index c2cc528..82f72ec 100644 --- a/source/conf.py +++ b/source/conf.py @@ -1,13 +1,17 @@ -# Configuration file for the Sphinx documentation builder. +# Configuration file for the Sphinx documentation builder. + +import sys, os + +sys.path.append(os.path.abspath('exts')) # -- Project information -project = 'Guide de montage Vheliotech' -copyright = '2023, Velo solaire pour tous' -author = 'Association Velo Solaire Pour Tous' +project = 'Guide de montage Vhéliotech' +copyright = '2023, Vélo solaire pour tous' +author = 'Association Vélo Solaire Pour Tous' -release = '1.0.0' -version = '1.0.0' +html_context = dict() +html_context['version'] = 'test' # -- General configuration @@ -19,6 +23,8 @@ extensions = [ 'sphinx.ext.intersphinx', 'myst_parser', 'sphinxcontrib.inkscapeconverter', + 'sphinx_multiversion', + 'rtd_current_version', ] myst_enable_extensions = [ @@ -55,5 +61,11 @@ html_css_files = [ 'html-version.css' ] -# -- Options for EPUB output -epub_show_urls = 'footnote' +html_theme_options = { + 'display_version': True +} + +# sphinx-multiversion settings +smv_branch_whitelist = r'^main$' +smv_tag_whitelist = r'^v[0-9\.]+$' +smv_released_pattern = r'^tags/.*$' diff --git a/source/exts/rtd_current_version.py b/source/exts/rtd_current_version.py new file mode 100644 index 0000000..5208d51 --- /dev/null +++ b/source/exts/rtd_current_version.py @@ -0,0 +1,14 @@ +# This tiny sphinx extension will simply copy the current_version (generated by sphinx_multiversion) to the 'version' entry in html_context, so that it is correctly displayed by the ReadTheDocs template +# You need to have the sphinx_multiversion extension as well + +def setup(app): + app.connect('config-inited', config_inited) + +def config_inited(app, config): + app.connect('html-page-context', html_page_context) + +def html_page_context(app, pagename, templatename, context, doctree): + try: + context['version'] = context['current_version'].name + except: + context['version'] = 'no_version_found' From b6c761eaa9ee687a0c661e55d2a8b708cfe13f4b Mon Sep 17 00:00:00 2001 From: Youen Date: Wed, 17 May 2023 21:26:03 +0200 Subject: [PATCH 2/5] Ajout d'un avertissement quand on consulte une ancienne version ou une version de travail --- source/_templates/page.html | 18 ++++++++++++++++++ source/conf.py | 5 +++-- 2 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 source/_templates/page.html diff --git a/source/_templates/page.html b/source/_templates/page.html new file mode 100644 index 0000000..5ab4d45 --- /dev/null +++ b/source/_templates/page.html @@ -0,0 +1,18 @@ +{% extends "!page.html" %} +{% block body %} +{% if current_version and latest_version and current_version != latest_version %} +
+

Attention

+

+ {% if current_version.is_released %} + Ceci est une ancienne version de la documentation. + La dernière version est la {{latest_version.name}}. + {% else %} + Ceci est une version en cours de développement. + La dernière version stable est la {{latest_version.name}}. + {% endif %} +

+
+{% endif %} +{{ super() }} +{% endblock %} diff --git a/source/conf.py b/source/conf.py index 82f72ec..b33db6e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -67,5 +67,6 @@ html_theme_options = { # sphinx-multiversion settings smv_branch_whitelist = r'^main$' -smv_tag_whitelist = r'^v[0-9\.]+$' -smv_released_pattern = r'^tags/.*$' +smv_tag_whitelist = r'^v[\d\.]+$' +smv_released_pattern = r'.*tags/v[\d\.]+' +smv_latest_version = 'v1.0.0' From 5f48f8f2d3c18b4db9628d7ec2a835d6b56089ab Mon Sep 17 00:00:00 2001 From: Youen Date: Thu, 18 May 2023 00:08:39 +0200 Subject: [PATCH 3/5] =?UTF-8?q?Ajout=20d'un=20m=C3=A9canisme=20pour=20d?= =?UTF-8?q?=C3=A9finir=20des=20donn=C3=A9es=20diff=C3=A9rentes=20dans=20ch?= =?UTF-8?q?aque=20version?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Possibilité de définir un lien vers le PDF différent dans chaque version --- Makefile | 2 +- source/_static/custom.css | 10 ++++++++++ source/_templates/versions.html | 10 ++++++++-- source/conf.py | 1 + source/exts/version_data.py | 21 +++++++++++++++++++++ 5 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 source/exts/version_data.py diff --git a/Makefile b/Makefile index 88a6fd1..360c427 100644 --- a/Makefile +++ b/Makefile @@ -27,7 +27,7 @@ html: html_versions: rm -rf $(BUILDDIR)/html_versions/* - sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html_versions" $(SPHINXOPTS) $(O) + sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html_versions" -D 'version_sourcedir=$${sourcedir}' $(SPHINXOPTS) $(O) pdf: weasyprint python3 sphinx-tools/make_pdf.py "$(SOURCEDIR)" "$(BUILDDIR)" diff --git a/source/_static/custom.css b/source/_static/custom.css index dadf769..602ca87 100644 --- a/source/_static/custom.css +++ b/source/_static/custom.css @@ -39,3 +39,13 @@ section#guide-de-montage h1 { h3 span.section-number, h4 span.section-number, h5 span.section-number, h6 span.section-number { display: none; } + +.rst-downloads { + padding: 12px; + padding-top: 0; +} + +.rst-downloads a { + color: #fcfcfc; + border: 1px solid grey; +} \ No newline at end of file diff --git a/source/_templates/versions.html b/source/_templates/versions.html index fb3355f..d6a963f 100644 --- a/source/_templates/versions.html +++ b/source/_templates/versions.html @@ -1,8 +1,8 @@ {%- if current_version %}
- Autres versions - v: {{ current_version.name }} + Autres versions + {{ current_version.name }}
@@ -23,5 +23,11 @@ {%- endif %}
+ + {%- if current_version_data.pdf_url %} +
+ Télécharger au format PDF +
+ {% endif %}
{%- endif %} \ No newline at end of file diff --git a/source/conf.py b/source/conf.py index b33db6e..1f9862d 100644 --- a/source/conf.py +++ b/source/conf.py @@ -25,6 +25,7 @@ extensions = [ 'sphinxcontrib.inkscapeconverter', 'sphinx_multiversion', 'rtd_current_version', + 'version_data' ] myst_enable_extensions = [ diff --git a/source/exts/version_data.py b/source/exts/version_data.py new file mode 100644 index 0000000..483b434 --- /dev/null +++ b/source/exts/version_data.py @@ -0,0 +1,21 @@ +# This module can read data from a python file in the source folder. This will read data from the version being built (as opposed to standard sphinx-multiversion behavior that executes python from the working copy) +# All global variables defined in file current_version_data.py will be put in html_context['current_version_data'] which allows to use them in HTML templates. + +import sys + +current_version_data = {} + +def setup(app): + app.add_config_value("version_sourcedir", '', "html") + app.connect('config-inited', config_inited) + +def config_inited(app, config): + app.connect('html-page-context', html_page_context) + try: + exec(open(app.config.version_sourcedir + '/current_version_data.py').read(), globals(), current_version_data) + except: + print('No file current_version_data.py found') + pass + +def html_page_context(app, pagename, templatename, context, doctree): + context['current_version_data'] = current_version_data From 31a36847f1262778b204cdb9d5debf9e86d7e572 Mon Sep 17 00:00:00 2001 From: Youen Date: Thu, 18 May 2023 01:02:38 +0200 Subject: [PATCH 4/5] =?UTF-8?q?La=20v1.0.0=20n'est=20pas=20encore=20publi?= =?UTF-8?q?=C3=A9e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 1f9862d..4ff7bf0 100644 --- a/source/conf.py +++ b/source/conf.py @@ -70,4 +70,4 @@ html_theme_options = { smv_branch_whitelist = r'^main$' smv_tag_whitelist = r'^v[\d\.]+$' smv_released_pattern = r'.*tags/v[\d\.]+' -smv_latest_version = 'v1.0.0' +smv_latest_version = 'v0.01' From dd4194670602b5e5280298e60e974ee21b5f0480 Mon Sep 17 00:00:00 2001 From: Youen Date: Thu, 18 May 2023 19:06:19 +0200 Subject: [PATCH 5/5] =?UTF-8?q?Am=C3=A9lioration=20du=20style=20du=20bouto?= =?UTF-8?q?n=20de=20t=C3=A9l=C3=A9chargement=20des=20PDF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/_static/custom.css | 1 - 1 file changed, 1 deletion(-) diff --git a/source/_static/custom.css b/source/_static/custom.css index 602ca87..31c03e9 100644 --- a/source/_static/custom.css +++ b/source/_static/custom.css @@ -47,5 +47,4 @@ h3 span.section-number, h4 span.section-number, h5 span.section-number, h6 span. .rst-downloads a { color: #fcfcfc; - border: 1px solid grey; } \ No newline at end of file