diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..9a05f09 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,51 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] + +# C extensions +*.so + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.installed.cfg +*.egg + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.cache +nosetests.xml +coverage.xml + +# Translations +*.mo +*.pot + +# Django stuff: +*.log + +# Sphinx documentation +build/ +docs/_build/ +source/.doctrees/ +source/_build/ +source/.vscode/ +.doctrees/ +source/locale/**/*.tmp +.vscode\settings.json diff --git a/doc/.pre-commit-config.yaml b/doc/.pre-commit-config.yaml new file mode 100644 index 0000000..fddfc70 --- /dev/null +++ b/doc/.pre-commit-config.yaml @@ -0,0 +1,33 @@ +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v2.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer +- repo: https://github.com/openstack-dev/bashate + rev: 2.0.0 + hooks: + - id: bashate + entry: bashate --error . --verbose --ignore=E006,E040 +- repo: https://github.com/Lucas-C/pre-commit-hooks-bandit + rev: v1.0.4 + hooks: + - id: python-bandit-vulnerability-check + args: [-l, --recursive] + files: .py$ +- repo: https://github.com/pre-commit/pygrep-hooks + rev: v1.5.1 + hooks: + - id: rst-backticks +- repo: local + hooks: + - id: sphinx-build + name: sphinx build + entry: python3.5 -m sphinx.cmd.build + args: [-a, -E, source, build] + language: system + files: ^source/ + types: [file] + pass_filenames: false diff --git a/doc/Jenkinsfile b/doc/Jenkinsfile new file mode 100644 index 0000000..ba316b2 --- /dev/null +++ b/doc/Jenkinsfile @@ -0,0 +1,252 @@ +pipeline { + agent { label 'debian-buster' } + options { + timestamps() + disableConcurrentBuilds() + buildDiscarder(logRotator(numToKeepStr: '10')) + } + + stages { + stage('Clean before launch'){ + steps{ + sh ''' + echo "clean" + make clean + rm -Rf ./build/ + ''' + } + } + stage('Setup RestructuredText'){ + steps { + sh ''' + echo "Installing requirements" + pip3 install -U pip setuptools + pip3 install -r requirements.txt --upgrade + ''' + } + } + stage('Gettext'){ + steps{ + sh ''' + echo "gettext and update po" + make gettext + sphinx-intl update -p build/locale/ -l fr + make clean + ''' + } + } + stage('Make HTML'){ + steps{ + sh ''' + make htmlen + make -e SPHINXOPTS="-D language='fr'" htmlfr + ''' + } + } + stage('Make EPUB'){ + steps{ + sh ''' + make epub_en + make -e SPHINXOPTS="-D language='fr'" epub_fr + ''' + } + } + stage('Make LatexPDF'){ + steps{ + sh ''' + echo "make latexpdf EN" + make latexpdf_en || true + + echo "make latexpdf FR" + make -e SPHINXOPTS="-D language='fr'" latexpdf_fr || true + ''' + } + } + stage('Copy static files'){ + steps{ + sh ''' + cp ./robots.txt build/en/doc + cp ./robots.txt build/fr/doc + mkdir ./build/en/doc/.well-known + mkdir ./build/fr/doc/.well-known + cp security.txt ./build/en/doc/.well-known + cp security.txt ./build/en/doc/.well-known + ''' + } + } + stage('Publish over SSH'){ + steps{ + sshPublisher alwaysPublishFromMaster: true, + publishers: [sshPublisherDesc(configName: 'root@doc.ad.tranquil.it', + transfers: [sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/doc/wapt/en/doc/', + remoteDirectorySDF: false, + removePrefix: 'build/en/doc/', + sourceFiles: 'build/en/doc/**'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/doc/wapt/fr/doc/', + remoteDirectorySDF: false, + removePrefix: 'build/fr/doc/', + sourceFiles: 'build/fr/doc/**'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/doc/wapt/fr/doc/', + remoteDirectorySDF: false, + removePrefix: 'build/fr/epub/', + sourceFiles: 'build/fr/epub/*.epub'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/doc/wapt/en/doc/', + remoteDirectorySDF: false, + removePrefix: 'build/en/epub/', + sourceFiles: 'build/en/epub/*.epub'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/doc/wapt/fr/doc/', + remoteDirectorySDF: false, + removePrefix: 'build/fr/latex/', + sourceFiles: 'build/fr/latex/WAPT.pdf'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/doc/wapt/en/doc/', + remoteDirectorySDF: false, + removePrefix: 'build/en/latex/', + sourceFiles: 'build/en/latex/WAPT.pdf') + ], + usePromotionTimestamp: false, + useWorkspaceInPromotion: false, + verbose: false)] + } + } + stage('Clean release prod'){ + when { + allOf { + branch 'master' + tag "release-*" + } + } + steps { + echo 'Cleanup prod' + sshPublisher alwaysPublishFromMaster: true, + publishers: [sshPublisherDesc(configName: 'root@wapt.fr', + transfers: [sshTransfer(execCommand: 'rm -rf /var/www/wapt.fr/fr/doc-1.8/*'), + sshTransfer(execCommand: 'rm -rf /var/www/wapt.fr/en/doc-1.8/*')], + usePromotionTimestamp: false, + useWorkspaceInPromotion: false, + verbose: false)] + } + } + stage('Publish release prod'){ + when { + allOf { + branch 'master' + tag "release-*" + } + } + steps { + echo 'Publishing to doc.wapt.fr' + sshPublisher alwaysPublishFromMaster: true, + publishers: [sshPublisherDesc(configName: 'root@wapt.fr', + transfers: [sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/wapt.fr/en/doc-1.8/', + remoteDirectorySDF: false, + removePrefix: 'build/en/doc/', + sourceFiles: 'build/en/doc/**'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/wapt.fr/fr/doc-1.8/', + remoteDirectorySDF: false, + removePrefix: 'build/fr/doc/', + sourceFiles: 'build/fr/doc/**'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/wapt.fr/en/doc-1.8/', + remoteDirectorySDF: false, + removePrefix: 'build/en/latex/', + sourceFiles: 'build/en/latex/WAPT.pdf'), + sshTransfer(excludes: '', + execCommand: '', execTimeout: 120000, + flatten: false, + makeEmptyDirs: false, + noDefaultExcludes: false, + patternSeparator: '[, ]+', + remoteDirectory: '/var/www/wapt.fr/fr/doc-1.8/', + remoteDirectorySDF: false, + removePrefix: 'build/fr/latex/', + sourceFiles: 'build/fr/latex/WAPT.pdf') + ], + usePromotionTimestamp: false, + useWorkspaceInPromotion: false, + verbose: false)] + } + } + } + + post { + success { + rocketSend message: "Successful Build - ${env.JOB_NAME} ${env.BUILD_NUMBER} - ${env.BUILD_TIMESTAMP} (<${env.BUILD_URL}|Open>)", + channel: 'documentation', + rawMessage: true + } + + failure { + rocketSend message: "Build Failed - ${env.JOB_NAME} ${env.BUILD_NUMBER} - ${env.BUILD_TIMESTAMP} (<${env.BUILD_URL}|Open>)", + channel: 'documentation', + rawMessage: true + } + + unstable { + rocketSend message: "Unstable Build - ${env.JOB_NAME} ${env.BUILD_NUMBER} - ${env.BUILD_TIMESTAMP} (<${env.BUILD_URL}|Open>)", + channel: 'documentation', + rawMessage: true + } + + aborted { + rocketSend message: "Build Aborted - ${env.JOB_NAME} ${env.BUILD_NUMBER} - ${env.BUILD_TIMESTAMP} (<${env.BUILD_URL}|Open>)", + channel: 'documentation', + rawMessage: true + } + always { + cleanWs() + } + } + } diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..46c9e87 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,277 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python3 -msphinx +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + + +.PHONY: htmlen +htmlen: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/en/doc + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/en/doc." + +.PHONY: htmlfr +htmlfr: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/fr/doc + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/fr/doc." + + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/WAPT.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/WAPT.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/WAPT" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/WAPT" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + + +.PHONY: epub_en +epub_en: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/en/epub + @echo + @echo "Build finished. The EN epub file is in $(BUILDDIR)/en/epub." + + +.PHONY: epub_fr +epub_fr: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/fr/epub + @echo + @echo "Build finished. The FR epub file is in $(BUILDDIR)/fr/epub." + + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + + +.PHONY: latexpdf_en +latexpdf_en: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/en/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/en/latex all-pdf -i + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/en/latex." + +.PHONY: latexpdf_fr +latexpdf_fr: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/fr/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/fr/latex all-pdf -i + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/fr/latex." + + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." + +.PHONY: slide +slide: + $(SPHINXBUILD) -b html slide $(BUILDDIR)/slide + @echo + @echo "Build finished. slide builder files are in $(BUILDDIR)/slide." diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..5d95a15 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,50 @@ +TIS-backup Documentation +======================== + +This is the documentation repository of the TIS-backup project. The documentation is provided under the licence CC-BY-SA. + +How to contribute? +================== + +You must install documentation tools and requirements before doing anything : + +```bash +sudo sh ./install_requirements.sh +``` + +Once installed, pre-commit checks (lint/syntax) are launched prior to committing your changes. To launch tests manually, you can run the following : + +```bash +pre-commit run --all-files +``` + +This should (take a while because sphinx-build) return : + +```bash +Trim Trailing Whitespace.................................................Passed +Fix End of Files.........................................................Passed +rst ``code`` is two backticks............................................Passed +sphinx build.............................................................Passed +``` + + +How to push documentation to public ? +===================================== + +Pushing the documentation through a rsync is bad. + +To publish WAPT documentation to public, a 'release-' tag must be set using git. + +Once a release tag has been set, it creates a tagged build which must be launched manually in Jenkins. + +```bash +git add * +git commit -m 'I have checked it builds without errors, trust me' +git push +git tag -a release-1.8.1.6694-doc -m "WAPT documentation publish for 1.8.1.6694" +git push origin --tags +``` + +Once that tag has been pushed, in Jenkins you have to re-scan the multibranches project and go to `Tags` tab, select your tag and build it. + +Wait for the entire build to go through, it will publish everything according to JenkinsFile procedure. diff --git a/doc/check_translation.py b/doc/check_translation.py new file mode 100644 index 0000000..4f701d8 --- /dev/null +++ b/doc/check_translation.py @@ -0,0 +1,21 @@ +import fnmatch +import os + +matches = [] +for root, dirnames, filenames in os.walk('source/locale/fr/LC_MESSAGES/'): + for filename in fnmatch.filter(filenames, '*.po'): + filename = os.path.join(root, filename) + matches.append(os.path.join(root, filename)) + data = open(filename,'r').readlines() + val = 0 + linenumber = 1 + for line in data: + if line.startswith('msgstr ""'): + val = 1 + continue + if line.strip()=='' and val==1: + print( "empty translation line %s in %s" % (linenumber,filename)) + val = 0 + if line.startswith('#, fuzzy'): + print ("fuzzy line %s in %s " % (linenumber,filename)) + linenumber = linenumber + 1 diff --git a/doc/install_requirements.sh b/doc/install_requirements.sh new file mode 100644 index 0000000..6259862 --- /dev/null +++ b/doc/install_requirements.sh @@ -0,0 +1,3 @@ +#!/bin/bash +pip3 install -r requirements.txt +pre-commit install diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..6489f8c --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,297 @@ +REM @ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source +set I18NSPHINXOPTS=%SPHINXOPTS% source +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. epub3 to make an epub3 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + echo. dummy to check syntax errors of document sources + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "htmlen" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% -D language=en %BUILDDIR%/en/doc + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/en/doc. + goto end +) + +if "%1" == "htmlfr" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/fr/doc + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/fr/doc. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\WAPT.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\WAPT.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "epub3" ( + %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +if "%1" == "dummy" ( + %SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. Dummy builder generates no files. + goto end +) + +:end diff --git a/doc/make_doc.bat b/doc/make_doc.bat new file mode 100644 index 0000000..2ee0017 --- /dev/null +++ b/doc/make_doc.bat @@ -0,0 +1,12 @@ +REM c:\python27\scripts\pip.exe install sphinx sphinx-intl sphinx-rtd-theme sphinxcontrib-googleanalytics sphinxcontrib-websupport sphinxcontrib.napoleon +REM set path=%path%;c:\python27\scripts\ +:: c:\python27\Scripts\sphinx-intl.exe + +rem make.bat clean +del /s /q build +rmdir /s /q build +make.bat gettext +sphinx-intl.exe update -p build/locale -l fr +rem make.bat clean +make.bat html +make.bat htmlfr diff --git a/doc/make_doc.sh b/doc/make_doc.sh new file mode 100644 index 0000000..5632829 --- /dev/null +++ b/doc/make_doc.sh @@ -0,0 +1,42 @@ +#!/bin/sh +set -e + +export http_proxy=http://srvproxy:8080 +export https_proxy=http://srvproxy:8080 + +echo "clean" +make clean + +rm -Rf ./build/ + +echo "gettext and update po" +make gettext +sphinx-intl update -p build/locale/ -l fr + +make clean + +echo "make html English" +make htmlen + +echo "make html French" +make -e SPHINXOPTS="-D language='fr'" htmlfr + +echo "make epub EN" +make epub_en + +echo "make epub FR" +make -e SPHINXOPTS="-D language='fr'" epub_fr + +echo "make latexpdf EN" +# we ignore errors from that build for now +make latexpdf_en || true + +echo "make latexpdf FR" +make -e SPHINXOPTS="-D language='fr'" latexpdf_fr || true + +cp ./robots.txt build/en/doc +cp ./robots.txt build/fr/doc +mkdir ./build/en/doc/.well-known +mkdir ./build/fr/doc/.well-known +cp security.txt ./build/en/doc/.well-known +cp security.txt ./build/en/doc/.well-known diff --git a/doc/make_doc_lite.sh b/doc/make_doc_lite.sh new file mode 100644 index 0000000..8818844 --- /dev/null +++ b/doc/make_doc_lite.sh @@ -0,0 +1,16 @@ +#!/bin/sh + +export http_proxy=http://srvproxy:8080 +export https_proxy=http://srvproxy:8080 + +echo "clean" +make clean + +echo "gettext" +make gettext + +echo "sphinx update po" +sphinx-intl update -p build/locale/ -l fr + +echo "make html English" +make htmlen diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..4795a23 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,6 @@ +docutils +sphinx==3.0.3 +sphinx_rtd_theme +sphinxjp.themes.revealjs +sphinx-intl +pre-commit diff --git a/doc/robots.txt b/doc/robots.txt new file mode 100644 index 0000000..d8dd88f --- /dev/null +++ b/doc/robots.txt @@ -0,0 +1,3 @@ +User-Agent: * +Disallow: +Sitemap: https://www.wapt.fr/sitemap.xml diff --git a/doc/run_checks.sh b/doc/run_checks.sh new file mode 100644 index 0000000..07fac21 --- /dev/null +++ b/doc/run_checks.sh @@ -0,0 +1,3 @@ +#!/bin/bash +pre-commit run --all-files +make linkcheck diff --git a/doc/security.txt b/doc/security.txt new file mode 100644 index 0000000..c5a28ca --- /dev/null +++ b/doc/security.txt @@ -0,0 +1,2 @@ +Contact: security@tranquil.it +Telephone: +33(0)240975755 diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/_static/css/custom.css b/doc/source/_static/css/custom.css new file mode 100644 index 0000000..fb8917c --- /dev/null +++ b/doc/source/_static/css/custom.css @@ -0,0 +1,3 @@ +.wy-nav-content { + max-width: 1050px +} diff --git a/doc/source/_static/css/ribbon.css b/doc/source/_static/css/ribbon.css new file mode 100644 index 0000000..ba1eae6 --- /dev/null +++ b/doc/source/_static/css/ribbon.css @@ -0,0 +1,77 @@ +/* @import url('../fonts/Noto-Sans.woff2'); */ +@font-face { + font-family: 'Noto Sans'; + src: url('../fonts/Noto-Sans.woff2') format('woff2'), + +/* The ribbons */ + +.corner-ribbon{ + width: 200px; + background: #e43; + position: absolute; + top: 25px; + left: -50px; + text-align: center; + line-height: 50px; + letter-spacing: 1px; + color: #f0f0f0; + transform: rotate(-45deg); + -webkit-transform: rotate(-45deg); +} + +/* Custom styles */ + +.corner-ribbon.sticky{ + position: fixed; +} + +.corner-ribbon.shadow{ + box-shadow: 0 0 3px rgba(0,0,0,.3); +} + +/* Different positions */ + +.corner-ribbon.top-left{ + top: 25px; + left: -50px; + transform: rotate(-45deg); + -webkit-transform: rotate(-45deg); +} + +.corner-ribbon.top-right{ + top: 25px; + right: -50px; + left: auto; + transform: rotate(45deg); + -webkit-transform: rotate(45deg); +} + +.corner-ribbon.bottom-left{ + top: auto; + bottom: 25px; + left: -50px; + transform: rotate(45deg); + -webkit-transform: rotate(45deg); +} + +.corner-ribbon.bottom-right{ + top: auto; + right: -50px; + bottom: 25px; + left: auto; + transform: rotate(-45deg); + -webkit-transform: rotate(-45deg); +} + +/* Colors */ + +.corner-ribbon.white{background: #f0f0f0; color: #555;} +.corner-ribbon.black{background: #333;} +.corner-ribbon.grey{background: #999;} +.corner-ribbon.blue{background: #39d;} +.corner-ribbon.green{background: #2c7;} +.corner-ribbon.turquoise{background: #1b9;} +.corner-ribbon.purple{background: #95b;} +.corner-ribbon.red{background: #e43;} +.corner-ribbon.orange{background: #e82;} +.corner-ribbon.yellow{background: #ec0;} diff --git a/doc/source/_static/favicon.ico b/doc/source/_static/favicon.ico new file mode 100644 index 0000000..ee9211a Binary files /dev/null and b/doc/source/_static/favicon.ico differ diff --git a/doc/source/_static/fonts/Noto-Sans.woff2 b/doc/source/_static/fonts/Noto-Sans.woff2 new file mode 100644 index 0000000..22818e7 Binary files /dev/null and b/doc/source/_static/fonts/Noto-Sans.woff2 differ diff --git a/doc/source/_static/fonts/fontawesome-webfont.woff2 b/doc/source/_static/fonts/fontawesome-webfont.woff2 new file mode 100644 index 0000000..4d13fc6 Binary files /dev/null and b/doc/source/_static/fonts/fontawesome-webfont.woff2 differ diff --git a/doc/source/_static/theme_overrides.css b/doc/source/_static/theme_overrides.css new file mode 100644 index 0000000..45807d2 --- /dev/null +++ b/doc/source/_static/theme_overrides.css @@ -0,0 +1,13 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + * this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } + } diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html new file mode 100644 index 0000000..4f1c8a6 --- /dev/null +++ b/doc/source/_templates/layout.html @@ -0,0 +1,16 @@ +{% extends "!layout.html" %} + +{% block footer %} +{{ super() }} + + + + + +{% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..91c10c6 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,475 @@ +# -*- coding: utf-8 -*- +# +# WAPT documentation build configuration file, created by +# sphinx-quickstart on Wed Nov 30 14:29:50 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'TISBackup' +copyright = '2020, Tranquil IT' +author = 'Tranquil IT' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.8' +# The full version, including alpha/beta/rc tags. +release = '1.8.2' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' +locale_dirs = ['locale/'] +gettext_compact = False + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +try: + import sphinx_rtd_theme + html_theme = "sphinx_rtd_theme" + html_favicon = "_static/favicon.ico" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + html_context = { + 'css_files': [ + '_static/css/custom.css', # overrides for wide tables in RTD theme + '_static/css/ribbon.css', + '_static/theme_overrides.css', # override wide tables in RTD theme + ], + } +except ImportError as e: + html_theme = 'alabaster' + html_theme_path = [] + + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +# html_title = 'WAPT v1.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'tisbackupdoc' + +# -- Linkcheck ------------------- +# make linkcheck +# URL patterns to ignore + +linkcheck_ignore = [r'http.*://.*mydomain.lan.*', + r'http.*://.*host_fqdn.*', + r'http://wapt.otherorganization.com/wapt/', + r'https://otherwapt.tranquil.it/waptdev', + r'http://user:pwd@host_fqdn:port'] + + +# -- Options for LaTeX output --------------------------------------------- + + +########## NOTE TIS +# le format de bouquin lulu n'est pas standard, il faut le rajouter dans le +# fichier en patchant le fichier /usr/share/texlive/texmf-dist/tex/latex/base/report.cls +# +# diff -r a/report.cls b/report.cls +# 71a72,74 +# > \DeclareOption{lulupaper} +# > {\setlength\paperheight {23.39cm}% +# > \setlength\paperwidth {15.59cm}} + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + 'papersize': 'lulupaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + 'pointsize': '9pt', + + # Additional stuff for the LaTeX preamble. + # + 'preamble': r'\batchmode', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', + 'sphinxsetup': 'hmargin={1.5cm,1.5cm}, vmargin={3cm,3cm}, marginpar=1cm', +} + + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'tisbackup.tex', 'TISBackup Documentation', 'Tranquil IT', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'tisbackup', 'TISBackup Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'tisbackup', 'TISBackup Documentation', + author, 'Tranquil IT', 'The objective of TISbackup is to benefit from file backups and centralized alert feedback on "reasonable" data volumes.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +# epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +# +# epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +# +# epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +# epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +# +# epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +# +# epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +# +# epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +# +# epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +# +# epub_tocdepth = 3 + +# Allow duplicate toc entries. +# +# epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +# +# epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +# +# epub_fix_images = False + +# Scale large images. +# +# epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# epub_show_urls = 'inline' + +# If false, no index is generated. +# +# epub_use_index = True diff --git a/doc/source/configuring_tisbackup.rst b/doc/source/configuring_tisbackup.rst new file mode 100644 index 0000000..7a8b433 --- /dev/null +++ b/doc/source/configuring_tisbackup.rst @@ -0,0 +1,26 @@ +.. Reminder for header structure: + Level 1: ==================== + Level 2: -------------------- + Level 3: ++++++++++++++++++++ + Level 4: """""""""""""""""""" + Level 5: ^^^^^^^^^^^^^^^^^^^^ + +.. meta:: + :description: Configuring the backup jobs + :keywords: Documentation, TISBackup, configuration, backup jobs + +.. |clap| image:: wapt-resources/clapping-hands-microsoft.png + :scale: 50% + :alt: Clapping hands + +Configuring the backup jobs +=========================== + +.. _configuring_backup_jobs: + +The configuration of the backups is done in an :mimetype:`.ini` file, +by default :file:`/etc/tis/tisbackup-config.ini`: + +* a global section where general parameters are specified; + +* then for each backup a section will be created; diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..89c7c86 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,93 @@ +.. Reminder for header structure: + Level 1: ==================== + Level 2: -------------------- + Level 3: ++++++++++++++++++++ + Level 4: """""""""""""""""""" + Level 5: ^^^^^^^^^^^^^^^^^^^^ + +.. meta:: + :description: TISBackup Documentation + :keywords: Documentation, TISBackup, introduction, welcome page, Welcome + +.. |date| date:: + +The objective of TISbackup is to benefit from file backups +and centralized alert feedback on "reasonable" data volumes +(of the order of a few TB). + +TISBackup allows: + +* to know if a recent backup exists; + +* to keep a history with deduplication at the file level (no duplicate backups); + +* to have an immediate view of the contents of a server or a server area + for data restoration ; + +* to export the last backup to an external media in order to transfer + it to a secure location; + +* to configure the backup cycle with a simple + and readable :mimetype:`.ini` file; + +* to work with a module mechanism to extend the type of backups + (https, rsync, postgres, mysql,) of virtual machines; + +Satisfying these needs stems from the need for a tool +to manage a vast pool of machines each hosting a multitude +of different software or services (different editors, +different hardware platforms and operating environments, etc.). +Finally, as the backup procedures of a publisher changed without any warning, +the remote backup mechanisms were regularly broken, which caused us some scares +with the mechanisms we were using before. + +Overview of existing solutions +============================== + +Different open source solutions exist but did not meet our specifications. + +Baccula +------- + +:program:`Baccula` is a high-performance solution for full backups on tape +and removable media. However, a restore can take a long time +and the storage of a history can be voluminous. +The backup is saved on a file system that is not readable by a Windows system. +An uninitiated "backup manager" will not be able to check the contents +of his backup from home. + +r-snapshot +---------- + +:program:`r-snapshot` almost corresponds to the specifications +but is complex to configure and any necessary modification +would have been difficult to develop as an overlay of the existing one: + +* the backups are organized by date then by zone which is the opposite + of what was desired; + +* it is not possible to configure different backup frequencies + according to the criticality levels of the servers; + +* finally, the deletion of obsolete backups is done in the same process + as the backups, which can be very long and can be problematic + if there is a problem during the backup. + +**... and now TISbackup ...** + +.. toctree:: + :maxdepth: 2 + :caption: Presenting TISBackup + +.. toctree:: + :maxdepth: 1 + :caption: Appendix + + tranquil-it-contacts.rst + +Indices and tables +================== + +* :ref:`genindex` + +* :ref:`search` diff --git a/doc/source/installing_tisbackup.rst b/doc/source/installing_tisbackup.rst new file mode 100644 index 0000000..682c314 --- /dev/null +++ b/doc/source/installing_tisbackup.rst @@ -0,0 +1,224 @@ +.. Reminder for header structure: + Level 1: ==================== + Level 2: -------------------- + Level 3: ++++++++++++++++++++ + Level 4: """""""""""""""""""" + Level 5: ^^^^^^^^^^^^^^^^^^^^ + +.. meta:: + :description: Installing and configuring TISBackup + :keywords: Documentation, TISBackup, installation, configuration + +.. |clap| image:: wapt-resources/clapping-hands-microsoft.png + :scale: 50% + :alt: Clapping hands + +Installing and configuring TISBackup on Debian +============================================== + +.. _base_debian_server_install: + +Setting up the GNU/Linux Debian server +-------------------------------------- + +In order to install a fresh Debian Linux 10 *Buster* (physical or virtual) +without graphical interface, please refer to the +`Debian GNU/Linux Installation Guide`_. + +Configuring network parameters +++++++++++++++++++++++++++++++ + +.. include:: wapt-resources/linux-server-naming.txt + +Configuring the name of the Debian server ++++++++++++++++++++++++++++++++++++++++++ + +.. hint:: + + The short name of the future TISBackup server must not be longer + than **15 characters** (the limit is due to *sAMAccountName* restriction + in Active Directory). + +The name of the TISBackup server must be a :abbr:`FQDN (Fully Qualified Domain Name)`, +that is to say it has both the server name and the DNS suffix. + +* modify the :file:`/etc/hostname` file and write the FQDN of the server; + +.. code-block:: bash + + # /etc/hostname of the TISBackup server + srvbackup.mydomain.lan + +* configure the :file:`/etc/hosts` file, be sure to put both the FQDN + and the short name of the server; + +.. code-block:: bash + + # /etc/hosts du waptserver + 127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 + ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 + 10.0.0.10 srvbackup.mydomain.lan srvbackup + +.. hint:: + + * on the line defining the DNS server IP address, be sure to have the IP + of the server (not 127.0.0.1), then the FQDN, then the short name; + + * do not change the line with *localhost*; + +Configuring the IP address of the Debian server ++++++++++++++++++++++++++++++++++++++++++++++++ + +* configure the IP address of the Debian Server + in the :file:`/etc/network/interfaces`; + +.. code-block:: bash + + # /etc/network/interfaces of the Debian server + auto eth0 + iface eth0 inet static + address 10.0.0.10 + netmask 255.255.255.0 + gateway 10.0.0.254 + +* apply the network configuration by rebooting the machine + with a :code:`reboot`; + +* if it has not already been done, create the DNS entry for the WAPT Server + in the Organization's Active Directory; + +* after reboot, configure the system language in English in order to have + non-localized logs for easier searching of common errors; + +.. code-block:: bash + + apt install locales-all + localectl set-locale LANG=en_US.UTF-8 + localectl status + +* check that the machine clock is on time (with NTP installed); + +.. code-block:: bash + + dpkg -l | grep ntp + service ntp status + date + +.. hint:: + + If the NTP package is not installed. + + .. code-block:: bash + + apt install ntp + systemctl enable ntp + systemctl start ntp + +* update and upgrade your Debian; + + .. code-block:: bash + + apt update + apt upgrade -y + +* install systemd; + + .. code-block:: bash + + apt install systemd + +* restart the Debian server; + + .. code-block:: bash + + reboot + +|clap| The Debian server is now ready. You may now go on to the next step +and :ref:`install TISBackup on your Debian`. + +.. _install_tisbackup_debian: + +Installing the TISBackup server on Debian Linux ++++++++++++++++++++++++++++++++++++++++++++++++ + +* install the required dependencies: + + .. code-block:: bash + + apt-get install unzip ssh rsync python-paramiko python-pyvmomi python-pexpect + +* retrieve the git sources from https://github.com/tranquilit/TISbackup_ + and place them in the :file:`/opt` folder on your server: + + .. code-block:: bash + + cd /opt/ + wget --no-check-certificate https://github.com/tranquilit/TISbackup/archive/master.zip + unzip master.zip + mv TISbackup-master tisbackup + chmod 755 /opt/tisbackup/tisbackup.py + ln -sb /opt/tisbackup/tisbackup.py /usr/local/bin/tisbackup + +* the :command:`tisbackup` command must return all *tisbackup* actions + directly to you. For more information on the actions go to :ref:``; + + .. code-block:: bash + + [root@srvbackup.mydomain.lan tisbackup]# tisbackup + ERROR : You must provide one action to perform + Usage: tisbackup -c configfile action + + TIS Files Backup system. + + action is either : + backup : launch all backups or a specific one if -s option is used + cleanup : removed backups older than retention period + checknagios : check all or a specific backup against max_backup_age parameter + dumpstat : dump the content of database for the last 20 backups + retryfailed : try to relaunch the last failed backups + listdrivers : list available backup types and parameters for config inifile + exportbackup : copy lastest OK backups from local to location defined by --exportdir parameter + register_existing : scan backup directories and add missing backups to database + +Configuring TISBackup ++++++++++++++++++++++ + +* create the directory for TISBackup configuration files: + + .. code-block:: bash + + mkdir /etc/tis/ + +* in the directory :file:`/opt/tisbackup/samples/`, you will find the files + :file:`config.ini.sample` and :file:`tisbackup-config.ini` + which you can use as examples. Copy one of these two files + into the :file:`/etc/tis` directory and we will describe in the next section + how to customize this files; + + .. code-block:: bash + + cp /opt/tisbackup/samples/tisbackup-config.ini.sample /etc/tis/tisbackup-config.ini + +Launching the backup scheduled task ++++++++++++++++++++++++++++++++++++ + +.. code-block:: bash + + cp /opt/tisbackup/samples/tisbackup.cron /etc/cron.d/tisbackup + +* modify the :file:`/etc/cron.d/tisbackup` file to indicate when to launch + the task; + +Generating the public and private certificates +++++++++++++++++++++++++++++++++++++++++++++++ + +* as root: + + .. code-block:: bash + + ssh-keygen -t rsa -b 2048 + +* press :kbd:`Enter` for each one of the steps; + +|clap| You may now go on to the next step +and :ref:`configure the backup jobs for your TISBackup`. diff --git a/doc/source/presenting_tisbackup.rst b/doc/source/presenting_tisbackup.rst new file mode 100644 index 0000000..84b7446 --- /dev/null +++ b/doc/source/presenting_tisbackup.rst @@ -0,0 +1,135 @@ +.. Reminder for header structure: + Level 1: ==================== + Level 2: -------------------- + Level 3: ++++++++++++++++++++ + Level 4: """""""""""""""""""" + Level 5: ^^^^^^^^^^^^^^^^^^^^ + +.. meta:: + :description: Technical background for TISBackup + :keywords: Documentation, TISBackup, technical background + +.. |clap| image:: wapt-resources/clapping-hands-microsoft.png + :scale: 50% + :alt: Clapping hands + +Technical background for TISBackup +================================== + +The deduplication of this solution is based on the hardlinks +of ext3/4 file systems used for storing backup files. + +The backup server must run :program:`rsync` in server mode, +and the workstations to be backed up must be equipped with :program:`rsync` +and :program:`ssh` (usually basic on machines running GNU/Linux, +with :program:`cygwin` (or another tool like :program:`cwrsync`) +for machines running MS Windows). + +tisbackup +--------- + +:program:`tisbackup` is a python script that the backup server runs +at regular intervals. The configuration file :file:`tisbackup.ini` contains +the details of the tasks to be executed. + +:program:`tisbackup` has different options for its execution, +available in the :command:`tisbackup --help` command, +the main ones being the following: + +* :command:`backup`: executes all scheduled backups; + +* :command:`cleanup`: examines the backups and deletes those + that are older than the defined maximum retention time ; + +* :command:`checknagios`: returns the content that can be viewed by nagios ; + +* :command:`retryfailed`: redoes the backups that previously failed; + +* :command:`exportbackup`: exports the last valid backups + to the specified location (remote, external media, ...); + +* :command:`register_existing`: scans the backups that have been made + and adds the missing ones to the database; + +tisbackup.ini +------------- + +:file:`tisbackup.ini` defines the backups to be executed and supervised. +It is written with a simple formalism. + +The different types of backups are: + +* ``rsync``: the backup of a directory by rsync using the rsync protocol; + +* ``rsync+ssh``: the backup of a directory by rsync with the ssh protocol; + +* ``mysql+ssh``: saving a mysql database in a gzipped sql file, + with the ssh protocol; + +* ``pgsql+ssh``: the backup of a postgresql database in a gzipped sql file, + with the ssh protocol; + +* ``xen-xva``: the backup of a virtual machine running on an XCP server + as an XVA file; + +* ``xen-meta-data``: the backup of XCP metadata from a virtualization server; + +* ``switch``: the backup of switches; + +* ``null``: null backup of a server that does not require a backup but for which + it is known to be taken into account (Nagios supervision); + +The first part of the :file:`tisbackup.ini` file, +starting with the ``[Global]`` tag, determines: + +* the path to the folder where the backups will be stored; + +* the maximum retention time of a backup (in days); + +* the maximum delay before triggering a nagios critical message (in hours); + +* possibly the limit of usable bandwidth; + +The rest of the file lists the different backups to be made, +with specific parameters for each type of backup: + +* name of the directory in the backup; + +* backup type; + +* server name; + +* directory (in case of a directory backup); + +* directories to be excluded (idem); + +* location of the ssh key to be used (private key on the backup server); + +* name of the database (in case of mysql or postgresql database backup); + +* ssh port number to use; + +* database user and password (in case of mysql or postgresql database backup); + +tisbackup.sql +------------- + +:file:`tisbackup.sql` is the :program:`sqlite` database available +on the backup server, in which the backup information of each +of the backed up areas is stored. It is used in particular to gather +the information necessary for Nagios. + +TISbackup GUI +------------- + +Also developed in python, TISbackup GUI is a graphical interface +that allows you to: + +* visualize the last backups; + +* export a backup to a USB media; + +* visualize the backups to be made; + +|clap| You may now go on to the next step +and :ref:`install TISBackup on your Debian`. diff --git a/doc/source/tranquil-it-contacts.rst b/doc/source/tranquil-it-contacts.rst new file mode 100644 index 0000000..3bfed41 --- /dev/null +++ b/doc/source/tranquil-it-contacts.rst @@ -0,0 +1,25 @@ +.. Reminder for header structure: + Level 1: ==================== + Level 2: -------------------- + Level 3: ++++++++++++++++++++ + Level 4: """""""""""""""""""" + Level 5: ^^^^^^^^^^^^^^^^^^^^ + +.. meta:: + :description: Contacting Tranquil IT + :keywords: WAPT, documentation, website, editor, + Twitter, Linkedin, Forum, Mailing List, official website + +.. _contact_tranquil_it: + +Contacting Tranquil IT +====================== + +Contact us for more informations: + +* Tranquil IT: https://www.tranquil.it/ +* Twitter: https://twitter.com/tranquil_it +* Linkedin: https://www.linkedin.com/company/tranquil-it +* Forum in French: https://forum.tranquil.it/ +* Forum in English: https://www.reddit.com/r/WAPT +* Mailing-list: https://lists.tranquil.it/listinfo/wapt diff --git a/doc/source/wapt-resources/apple.png b/doc/source/wapt-resources/apple.png new file mode 100644 index 0000000..0a8b537 Binary files /dev/null and b/doc/source/wapt-resources/apple.png differ diff --git a/doc/source/wapt-resources/cyber-security.png b/doc/source/wapt-resources/cyber-security.png new file mode 100644 index 0000000..fee06dd Binary files /dev/null and b/doc/source/wapt-resources/cyber-security.png differ diff --git a/doc/source/wapt-resources/debian.png b/doc/source/wapt-resources/debian.png new file mode 100644 index 0000000..e2116e2 Binary files /dev/null and b/doc/source/wapt-resources/debian.png differ diff --git a/doc/source/wapt-resources/deprecated.png b/doc/source/wapt-resources/deprecated.png new file mode 100644 index 0000000..f8d7e60 Binary files /dev/null and b/doc/source/wapt-resources/deprecated.png differ diff --git a/doc/source/wapt-resources/grinning-face.png b/doc/source/wapt-resources/grinning-face.png new file mode 100644 index 0000000..f2296d6 Binary files /dev/null and b/doc/source/wapt-resources/grinning-face.png differ diff --git a/doc/source/wapt-resources/linux-server-naming.txt b/doc/source/wapt-resources/linux-server-naming.txt new file mode 100644 index 0000000..27e411c --- /dev/null +++ b/doc/source/wapt-resources/linux-server-naming.txt @@ -0,0 +1,22 @@ +.. Reminder for header structure: + Niveau 1: ==================== + Niveau 2: -------------------- + Niveau 3: ++++++++++++++++++++ + Niveau 4: """""""""""""""""""" + Niveau 5: ^^^^^^^^^^^^^^^^^^^^ + +The different parameters presented below are not specific to TISBackup; +you may adapt them as required for your environment. + +Modify the following files in order to get a proper named +:abbr:`FQDN (Fully Qualified Domain Name)` and network addressing strategy. + +In the following example: + +* the :term:`FQDN` name is *srvbackup.mydomain.lan*; + +* the short-name of the TISBackup Server is *srvbackup*; + +* the :abbr:`DNS (Domain Name Service)` suffix is *mydomain.lan*; + +* the IP address is *10.0.0.10/24*; \ No newline at end of file diff --git a/doc/source/wapt-resources/nok.png b/doc/source/wapt-resources/nok.png new file mode 100644 index 0000000..1474780 Binary files /dev/null and b/doc/source/wapt-resources/nok.png differ diff --git a/doc/source/wapt-resources/ok.png b/doc/source/wapt-resources/ok.png new file mode 100644 index 0000000..9a6925f Binary files /dev/null and b/doc/source/wapt-resources/ok.png differ diff --git a/doc/source/wapt-resources/pinguin.png b/doc/source/wapt-resources/pinguin.png new file mode 100644 index 0000000..26c137e Binary files /dev/null and b/doc/source/wapt-resources/pinguin.png differ diff --git a/doc/source/wapt-resources/redhat.png b/doc/source/wapt-resources/redhat.png new file mode 100644 index 0000000..5c659a1 Binary files /dev/null and b/doc/source/wapt-resources/redhat.png differ diff --git a/doc/source/wapt-resources/suse.png b/doc/source/wapt-resources/suse.png new file mode 100644 index 0000000..451cfff Binary files /dev/null and b/doc/source/wapt-resources/suse.png differ diff --git a/doc/source/wapt-resources/ubuntu.png b/doc/source/wapt-resources/ubuntu.png new file mode 100644 index 0000000..c474ba8 Binary files /dev/null and b/doc/source/wapt-resources/ubuntu.png differ diff --git a/doc/source/wapt-resources/windows.png b/doc/source/wapt-resources/windows.png new file mode 100644 index 0000000..221ca57 Binary files /dev/null and b/doc/source/wapt-resources/windows.png differ diff --git a/doc/source/wapt-resources/work-in-progress.png b/doc/source/wapt-resources/work-in-progress.png new file mode 100644 index 0000000..9838834 Binary files /dev/null and b/doc/source/wapt-resources/work-in-progress.png differ