From a5d9e32ade39b8c2c11762a71571cc3ebd6178f4 Mon Sep 17 00:00:00 2001 From: garciadeblas Date: Wed, 16 Mar 2022 01:27:24 +0100 Subject: [PATCH 1/2] Support of multiple versions in OSM user guide Signed-off-by: garciadeblas --- Makefile | 3 +++ _templates/versions.html | 27 ++++++++++++++++++++++++ conf.py | 11 ++++++++++ index.md | 7 ++++--- requirements.txt | 1 + tox.ini | 44 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 90 insertions(+), 3 deletions(-) create mode 100644 _templates/versions.html create mode 100644 tox.ini diff --git a/Makefile b/Makefile index d4bb2cb..605bad4 100644 --- a/Makefile +++ b/Makefile @@ -16,5 +16,8 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +html: Makefile + sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" + %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/_templates/versions.html b/_templates/versions.html new file mode 100644 index 0000000..31a1257 --- /dev/null +++ b/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} diff --git a/conf.py b/conf.py index b51879f..d4d2af3 100644 --- a/conf.py +++ b/conf.py @@ -37,6 +37,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.githubpages', 'recommonmark', 'sphinx_markdown_tables', + 'sphinx_multiversion', ] source_suffix = { @@ -94,3 +95,13 @@ html_theme_options = { #html_logo = 'assets/osm_logo.png' html_logo = 'assets/osm_logo.svg' +smv_current_version = 'master' +smv_tag_whitelist = None +#smv_tag_whitelist = r'^v\d+\.\d+$' +#smv_branch_whitelist = None +#smv_branch_whitelist = r'^v\d+\.\d+$' +smv_branch_whitelist = r'(v11|v10)' +#smv_remote_whitelist = 'None' +smv_remote_whitelist = r'(origin)' +smv_released_pattern = r'(master)' + diff --git a/index.md b/index.md index 78a2e93..6f0994c 100644 --- a/index.md +++ b/index.md @@ -23,6 +23,7 @@ 11. [ANNEX 3: Reference of OSM's Information Model](11-osm-im.md) 12. [ANNEX 4: Reference of OSM's Northbound Interface](12-osm-nbi.md) 13. [ANNEX 5: OpenVIM installation](13-openvim-installation.md) -14. [ANNEX 6: Tests to validate VIM capabilities from OSM](14-tests-for-vim-validation.md) -15. [ANNEX 7: Kubernetes installation and requirements](15-k8s-installation.md) -16. [ANNEX 8: Setting up an LXD Cluster](16-lxd-cluster.md) +15. [ANNEX 6: Kubernetes installation and requirements](15-k8s-installation.md) +16. [ANNEX 7: Setting up an LXD Cluster](16-lxd-cluster.md) +17. [ANNEX 8: TACACS Based Authentication Support In OSM](18-tacacs-based-authentication.md) + diff --git a/requirements.txt b/requirements.txt index e5fa376..4b72249 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ sphinx sphinx_rtd_theme sphinxcontrib-versioning +sphinx-multiversion recommonmark sphinx-markdown-tables diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..ebbda64 --- /dev/null +++ b/tox.ini @@ -0,0 +1,44 @@ +####################################################################################### +# Copyright ETSI Contributors and Others. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. +####################################################################################### + +[tox] +envlist = test + +[testenv] +usedevelop = True +basepython = python3 +setenv = VIRTUAL_ENV={envdir} + PYTHONDONTWRITEBYTECODE = 1 +deps = -r{toxinidir}/requirements.txt +parallel_show_output = true + + +####################################################################################### +# This is a test of sphinxcontrib-versioning. +# +# This was not used in the end because it is no longer maintained. Besides, it was not +# working well from scratch, requiring some updates in the library (see commands below). +# +# Instead, sphinx-multiversion was used and incorporated in Makefile. +# This is kept as a reference for the future in case we want to try again +####################################################################################### +[testenv:sphinx-versioning] +skip_install = true +commands = + /usr/bin/sed -i "s|from sphinx import application, build_main.*|from sphinx import application\nfrom sphinx.cmd.build import build_main|" {envdir}/lib/python3.8/site-packages/sphinxcontrib/versioning/sphinx_.py + sphinx-versioning build --help + -- GitLab From a3c909b0ea5d8eff391322a640612e28e5e033ad Mon Sep 17 00:00:00 2001 From: garciadeblas Date: Sun, 3 Apr 2022 22:01:50 +0200 Subject: [PATCH 2/2] Updated Makefile, conf.py and template to set the final versions and look and feel to be published Signed-off-by: garciadeblas --- Makefile | 1 + _templates/versions.html | 15 ++++++--------- conf.py | 9 ++++++--- upload-doc.sh | 4 ++-- 4 files changed, 15 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index 605bad4..2cfb8f0 100644 --- a/Makefile +++ b/Makefile @@ -18,6 +18,7 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). html: Makefile sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" + ./fix_cross_references.sh %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/_templates/versions.html b/_templates/versions.html index 31a1257..c3b4d4a 100644 --- a/_templates/versions.html +++ b/_templates/versions.html @@ -6,22 +6,19 @@
- {%- if versions.tags %}
-
Tags
+
Versions
+ {%- if versions.tags %} {%- for item in versions.tags %}
{{ item.name }}
{%- endfor %} -
- {%- endif %} - {%- if versions.branches %} -
-
Branches
- {%- for item in versions.branches %} + {%- endif %} + {%- if versions.branches %} + {%- for item in versions.branches|sort(attribute="name",reverse=True) %}
{{ item.name }}
{%- endfor %} + {%- endif %}
- {%- endif %}
{%- endif %} diff --git a/conf.py b/conf.py index d4d2af3..498b873 100644 --- a/conf.py +++ b/conf.py @@ -95,13 +95,16 @@ html_theme_options = { #html_logo = 'assets/osm_logo.png' html_logo = 'assets/osm_logo.svg' -smv_current_version = 'master' -smv_tag_whitelist = None +smv_current_version = 'latest' +#smv_tag_whitelist = None #smv_tag_whitelist = r'^v\d+\.\d+$' +smv_tag_whitelist = 'latest' #smv_branch_whitelist = None #smv_branch_whitelist = r'^v\d+\.\d+$' smv_branch_whitelist = r'(v11|v10)' #smv_remote_whitelist = 'None' smv_remote_whitelist = r'(origin)' -smv_released_pattern = r'(master)' +smv_released_pattern = r'(latest|v11|v10)' +#smv_outputdir_format = 'versions/{config.release}' # Use "versions" as parent directory and the "release" variable from conf.py +#smv_outputdir_format = 'versions/{ref.name}' diff --git a/upload-doc.sh b/upload-doc.sh index ac027c5..6075d87 100755 --- a/upload-doc.sh +++ b/upload-doc.sh @@ -12,9 +12,9 @@ make clean make html # -# Fix cross-references +# Fix cross-references (already fixed in Makefile) # -./fix_cross_references.sh +# ./fix_cross_references.sh # # Get credentias (file or interactive) -- GitLab