From 090886d0c3e9d0c01a0e4e35fa9b7d2eb3d3781e Mon Sep 17 00:00:00 2001 From: garciadeblas Date: Fri, 10 Jun 2022 10:51:56 +0200 Subject: [PATCH] Simplify documentation build and publish via tox Signed-off-by: garciadeblas --- .gitignore | 1 + README.md | 18 +++------ requirements.in | 23 +++++++++++ requirements.txt | 101 ++++++++++++++++++++++++++++++++++++++++++++--- tox.ini | 49 +++++++++++++++++++++-- upload-doc.sh | 15 ++----- 6 files changed, 173 insertions(+), 34 deletions(-) create mode 100644 requirements.in diff --git a/.gitignore b/.gitignore index 6a35bda..2765456 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ _build*/ local/ +.tox/ diff --git a/README.md b/README.md index 4bff028..6d555d9 100644 --- a/README.md +++ b/README.md @@ -15,23 +15,15 @@ It is published at [https://osm.etsi.org/docs/user-guide/](https://osm.etsi.org/ This markdown format can be easily exported by installing and using [Sphinx](http://www.sphinx-doc.org/en/master/) in your local machine. -Install the required packages: - -```bash -sudo -H python3 -m pip install -r requirements.txt -``` - Before proceeding, **make sure that there are no uncommitted changes in your workdir or your staging area** (in case of doubt, do all the corresponding `add`'s and `commit`'s). Then run: ```bash -make clean -make html -./fix_cross_references.sh +tox -e build ``` -The generated HTML output is stored in `_build/html`. +The generated HTML output is stored in `_build/html` with separate folders for each version. ## Local publication @@ -45,11 +37,11 @@ Then you can check the generated HTML output with a local web browser pointing t ## Publication in ETSI OSM site -For regular publication in ETSI site, there is an all-in-one script that is highly convenient for regular or automated use, since builds the HTML documents and uploads them to the FTP in a single step (it also performs a backup for safety): +For regular publication in ETSI site, you can run this to upload the HTML documents to the FTP (it also performs a backup for safety): ```bash -./upload-doc.sh +tox -e publish ``` -The script searchs for authorized EOL credentials in `local/.credentials`. In case the file does not exist, the user is prompted for valid EOL username and password. +This script uses `upload_doc.sh` behind the scenes. It searchs for authorized EOL credentials in `local/.credentials`. In case the file does not exist, the user is prompted for valid EOL username and password. diff --git a/requirements.in b/requirements.in new file mode 100644 index 0000000..9ab570d --- /dev/null +++ b/requirements.in @@ -0,0 +1,23 @@ +####################################################################################### +# 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. +####################################################################################### + +sphinx +sphinx_rtd_theme +sphinxcontrib-versioning +sphinx-multiversion +recommonmark +sphinx-markdown-tables diff --git a/requirements.txt b/requirements.txt index 4b72249..e87b1cb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,95 @@ -sphinx -sphinx_rtd_theme -sphinxcontrib-versioning -sphinx-multiversion -recommonmark -sphinx-markdown-tables +####################################################################################### +# 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. +####################################################################################### + +alabaster==0.7.12 + # via sphinx +babel==2.10.1 + # via sphinx +certifi==2022.5.18.1 + # via requests +charset-normalizer==2.0.12 + # via requests +click==8.1.3 + # via sphinxcontrib-versioning +colorclass==2.2.2 + # via sphinxcontrib-versioning +commonmark==0.9.1 + # via recommonmark +docutils==0.17.1 + # via + # recommonmark + # sphinx + # sphinx-rtd-theme +idna==3.3 + # via requests +imagesize==1.3.0 + # via sphinx +importlib-metadata==4.11.4 + # via + # markdown + # sphinx +jinja2==3.1.2 + # via sphinx +markdown==3.3.7 + # via sphinx-markdown-tables +markupsafe==2.1.1 + # via jinja2 +packaging==21.3 + # via sphinx +pygments==2.12.0 + # via sphinx +pyparsing==3.0.9 + # via packaging +pytz==2022.1 + # via babel +recommonmark==0.7.1 + # via -r requirements.in +requests==2.28.0 + # via sphinx +snowballstemmer==2.2.0 + # via sphinx +sphinx==5.0.1 + # via + # -r requirements.in + # recommonmark + # sphinx-multiversion + # sphinx-rtd-theme + # sphinxcontrib-versioning +sphinx-markdown-tables==0.0.15 + # via -r requirements.in +sphinx-multiversion==0.2.4 + # via -r requirements.in +sphinx-rtd-theme==1.0.0 + # via -r requirements.in +sphinxcontrib-applehelp==1.0.2 + # via sphinx +sphinxcontrib-devhelp==1.0.2 + # via sphinx +sphinxcontrib-htmlhelp==2.0.0 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.3 + # via sphinx +sphinxcontrib-serializinghtml==1.1.5 + # via sphinx +sphinxcontrib-versioning==2.2.1 + # via -r requirements.in +urllib3==1.26.9 + # via requests +zipp==3.8.0 + # via importlib-metadata diff --git a/tox.ini b/tox.ini index ebbda64..a347cf5 100644 --- a/tox.ini +++ b/tox.ini @@ -16,11 +16,14 @@ ####################################################################################### [tox] -envlist = test +envlist = build +skipsdist = True + +[tox:jenkins] +toxworkdir = /tmp/.tox [testenv] -usedevelop = True -basepython = python3 +basepython = python3.8 setenv = VIRTUAL_ENV={envdir} PYTHONDONTWRITEBYTECODE = 1 deps = -r{toxinidir}/requirements.txt @@ -42,3 +45,43 @@ 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 + +####################################################################################### +[testenv:build] +deps = {[testenv]deps} +commands = + rm -rf _build/html + sphinx-multiversion . _build/html + sh -c './fix_cross_references.sh' +whitelist_externals = + sh + rm + + +####################################################################################### +[testenv:publish] +deps = {[testenv]deps} +commands = + rm -rf _build/html + sphinx-multiversion . _build/html + sh -c './upload_doc.sh' +whitelist_externals = + sh + rm + + +####################################################################################### +[testenv:pip-compile] +deps = pip-tools==6.6.2 +skip_install = true +whitelist_externals = bash + [ +commands = + - bash -c "for file in requirements*.in ; do \ + UNSAFE="" ; \ + if [[ $file =~ 'dist' ]] ; then UNSAFE='--allow-unsafe' ; fi ; \ + pip-compile -rU --no-header $UNSAFE $file ;\ + out=`echo $file | sed 's/.in/.txt/'` ; \ + sed -i -e '1 e head -16 tox.ini' $out ;\ + done" + diff --git a/upload-doc.sh b/upload-doc.sh index cd567fe..c128c4e 100755 --- a/upload-doc.sh +++ b/upload-doc.sh @@ -1,21 +1,10 @@ #!/bin/bash # -# Script to upload documentation to ETSI site +# Script to generate documentation and upload it to ETSI site # source ./env -# -# Generate Statit Site -# -make clean -make html - -# -# Fix cross-references (already fixed in Makefile) -# -# ./fix_cross_references.sh - # # Get credentias (file or interactive) # @@ -31,6 +20,8 @@ fi lftp ${FTP_OPTS} -u ${USERNAME},${PASSWORD} ${SERVER} << ! set ftp:ssl-allow no + set ftp:use-allo false + set ftp:prefer-epsv false lcd _build cd Documentation -- GitLab