[doc] Fix and improve documentation

- Various content update across the board
- Update Sphinx and theme versions
- Add build job on CI

.github/workflows/tests.yaml

@@ -70,6 +70,32 @@ jobs:
         name: codecov-umbrella
         fail_ci_if_error: false
 
+  tests-docs:
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        shell: bash
+
+    name: Build documentation
+    steps:
+
+    - name: Acquire sources
+      uses: actions/checkout@v3
+
+    - name: Setup Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '2.7'
+        architecture: 'x64'
+        cache: 'pip'
+        cache-dependency-path: 'requirements-docs.txt'
+
+    - name: Invoke Sphinx
+      run: |
+        pip install virtualenv
+        make docs-html
+
   tests-ui:
     runs-on: ${{ matrix.os }}
     strategy:

CHANGES.rst

@@ -2386,15 +2386,12 @@ Bug fixes and minor updates
 2013-10-24 0.0.7
 ================
 
-feature:
 - backpropagate current basket entries into checkbox state
 - display "inventor" attribute
 - add portfolio demo frameset
 - add ship-mode=single-bibdata
 - fix: be more graceful if applicants or inventors are missing from data
-- renamed ingress query parameters "ship_*" to "ship-*"
-
-tech:
+- renamed ingress query parameters ``ship_*`` to ``ship-*``
 - route refactoring
 - ui refactoring: more responsive through "twitter bootstrap responsive css"
 

Makefile

@@ -153,14 +153,18 @@ clear-cache:
 
 docs-virtualenv:
 	$(eval venvpath := ".venv_sphinx")
-	@test -e $(venvpath)/bin/python || `command -v virtualenv` --python=`command -v python` --no-site-packages $(venvpath)
+	@test -e $(venvpath)/bin/python || `command -v virtualenv` --python=`command -v python2` $(venvpath)
 	@$(venvpath)/bin/pip --quiet install --requirement requirements-docs.txt
 
 docs-html: docs-virtualenv
 	$(eval venvpath := ".venv_sphinx")
 	touch docs/index.rst
 	export SPHINXBUILD="`pwd`/$(venvpath)/bin/sphinx-build"; cd docs; make html
 
+docs-linkcheck: docs-virtualenv
+	$(eval venvpath := ".venv_sphinx")
+	export SPHINXBUILD="`pwd`/$(venvpath)/bin/sphinx-build"; cd docs; make linkcheck
+
 pdf-EP666666:
 	/usr/local/bin/wkhtmltopdf \
 		--no-stop-slow-scripts --debug-javascript \

README.rst

@@ -31,7 +31,7 @@ building arbitrary vendor solutions.
 
   .. image:: https://img.shields.io/pypi/l/patzilla.svg
 
-  .. image:: https://img.shields.io/pypi/dm/patzilla.svg
+  .. image:: https://pepy.tech/badge/patzilla/month
 
 - **Code status**:
 
@@ -116,17 +116,18 @@ Auxiliary data sources:
 
 Getting started
 ===============
-Getting started with the software or deploying it yourself is quite easy if you are familiar with Python.
-We will only cover development here, see the `install documentation`_ page about how to install, configure
-and run an instance.
-The software should work on any other Linux or BSD distribution, but this is beyond the scope of the README.
 
-It runs on Python 2.7, but is not ready for Python 3.6 yet. Contributions are welcome!
+Getting started with the software or deploying it yourself is quite easy if
+you are familiar with Python or Docker. See the `install documentation`_ page
+about how to install, configure and run PatZilla.
 
 
 Project information
 ===================
-The source code of »PatZilla IP Navigator« is available under an open source license using the brand name »PatZilla«.
+
+The source code of »PatZilla IP Navigator« is available under an open source
+license using the brand name »PatZilla«.
+
 For further details, please visit:
 
 - `PatZilla on GitHub <https://github.com/ip-tools/patzilla>`_
@@ -138,12 +139,17 @@ History
 =======
 The software got some applause from professional researchers for its unique user
 interface and rich feature set when it was released to the first audience in 2014.
-We hear from our users they are still having a great pleasure working with it on a daily basis.
+We hear from our users they are still having a great pleasure working with it on
+a daily basis.
 
 After four years of development, the source code finally gets released under an
 open source license in 2017. We are looking forward to opening up the development
 process as well, every kind of participation and support is very much welcome.
 
+After a project hiatus from 2020 to 2022, the code base is getting a refresh,
+many software tests have been added, and the aim is to finish migration to
+Python 3 within the end of the year.
+
 
 Contributing
 ============
@@ -174,18 +180,17 @@ Elmyra UG. `Elmyra UG`_ is the software development company that’s
 spearheading the ongoing development and as such will ensure
 continuity for the project.
 
-If you’re using PatZilla in your company and you need support or custom
-development or support, feel free to get in touch with us. We are happy
-to receive respective inquiries at info@elmyra.de.
+If you are using PatZilla in your company, and you need support or custom
+development, feel free to get in touch with us by sending corresponding
+inquiries to info@elmyra.de.
 
 In this way, you are contributing to the ongoing maintenance and further
-development of PatZilla. As it still is a reasonably young project, it
-needs all support it can get.
+development of PatZilla.
 
 
 .. _GNU-AGPL-3.0: https://docs.ip-tools.org/patzilla/_static/license/GNU-AGPL-3.0.txt
 .. _EUPL-1.2: https://docs.ip-tools.org/patzilla/_static/license/EUPL-1.2.txt
-.. _notices about licenses of third-party components: https://docs.ip-tools.org/patzilla/license/THIRD-PARTY-NOTICES.html
+.. _notices about licenses of third-party components: https://github.com/ip-tools/patzilla/blob/main/THIRD-PARTY-NOTICES.rst
 .. _install documentation: https://docs.ip-tools.org/patzilla/install/
 
 .. _Elmyra UG: https://elmyra.de/

docs/index.rst

@@ -3,75 +3,40 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. image:: https://img.shields.io/badge/Python-2.7-green.svg
-    :target: https://github.com/ip-tools/patzilla
-
-.. image:: https://img.shields.io/pypi/v/patzilla.svg
-    :target: https://pypi.org/project/patzilla/
-
-.. image:: https://img.shields.io/github/tag/ip-tools/patzilla.svg
-    :target: https://github.com/ip-tools/patzilla
-
-|
-
-PatZilla: Patent information research for humans
-================================================
-
-PatZilla is a modular patent information research platform and
-data integration toolkit. It features an efficient user interface
-and access to multiple data sources.
-
-The system provides convenient access to the OPS service from EPO and
-other professional fulltext patent databases in its standalone version.
-You can also use its software components and interfaces for
-building arbitrary vendor solutions.
-
-
 .. highlight:: bash
 
-.. toctree::
-    :maxdepth: 1
-    :caption: About
+.. include:: README.rst
 
-    README <README>
 
 .. toctree::
     :maxdepth: 1
     :caption: Features
+    :hidden:
 
     datasource/index
 
-
-----
-
 .. toctree::
     :maxdepth: 1
-    :caption: Basic setup
+    :caption: Setup
+    :hidden:
 
     install/index
     configure/index
     running/index
 
-.. toctree::
-    :maxdepth: 1
-    :caption: Advanced setup
-
-    install/sandbox
-    install/production
-
 .. toctree::
     :maxdepth: 1
     :caption: Development
+    :hidden:
 
-    development/release
     Changelog <development/CHANGES>
     development/contribute
     Contributors <development/CONTRIBUTORS>
 
 .. toctree::
     :maxdepth: 1
     :caption: License and support
+    :hidden:
 
     license/index
-    development/support
-
+    support

docs/install/docker.rst

@@ -15,8 +15,8 @@ This part of the documentation covers the building of Docker images
 and running PatZilla within a Docker container.
 
 The provided ``Dockerfile`` is meant to build Docker images for official
-releases of PatZilla. The ``patzilla`` package will be installed from
-`PatZilla on PyPI`_, so this is not meant for development purposes.
+releases of PatZilla. Because the ``patzilla`` package will be installed from
+`PatZilla on PyPI`_, this setup is not suitable for development purposes.
 
 
 ********

docs/install/index.rst

@@ -5,72 +5,17 @@
 ############
 Installation
 ############
+
 This part of the documentation covers the installation of PatZilla.
 The first step to using any software package is getting it properly installed.
 Please read this section carefully.
 
 After successfully installing the software, you might want to
 follow up with its :ref:`configuration`.
 
+Installation of PatZilla can be done natively on your system, or by using
+Docker. Depending on your preferences, please follow either
+:ref:`install-linux-macos` or :ref:`install-docker`.
 
-.. _installing:
-
-*******************
-Installing PatZilla
-*******************
-The following documentation is for Debian GNU/Linux or derivates.
-We appreciate contributions in form of walkthroughs about how to
-install PatZilla on other distributions and platforms.
-
-
-.. _install-minimum-requirements:
-
-Minimum prerequisites
-=====================
-Foundation: MongoDB_, PDFtk_, pdfimages_ and ImageMagick_::
-
-    # Debian Linux
-    apt install mongodb-clients mongodb-server pdftk poppler-utils imagemagick unoconv
-
-    # Mac OS X
-    # https://github.com/turforlag/homebrew-cervezas
-    # https://github.com/spl/homebrew-pdftk (deprecated)
-    brew tap turforlag/homebrew-cervezas
-    brew install mongodb pdftk poppler imagemagick unoconv
-
-Python stack::
-
-    apt install python2.7 python2.7-dev python-virtualenv build-essential libxml2-dev libxslt1-dev zlib1g-dev
-
-.. note::
-
-    As PatZilla is currently being shipped as Python sdist package only, we need to have
-    some build tools and header files installed on the system before running the installation.
-    This will change as soon as Debian or other distribution packages will be available.
-
-
-Distribute & Pip
-================
-The recommended way to install PatZilla is with `pip <http://www.pip-installer.org/>`_::
-
-    pip install patzilla
-
-You might want to verify the installation actually worked::
-
-    patzilla --version
-    patzilla 0.142.5
-
-If you need an older version, please visit
-the `release history <https://pypi.org/project/patzilla/#history>`_
-of `PatZilla on PyPI <https://pypi.org/project/patzilla/>`_.
-
-
-.. tip::
-
-    As PatZilla pulls in a significant amount of Python package dependencies,
-    you might want to consider installing the software isolated from the system Python
-    by using "virtualenv" before proceeding with ``pip install patzilla``::
-
-        virtualenv --python=python2 .venv2
-        source .venv2/bin/activate
-
+If you are interested in contributing to PatZilla, you should setup
+a development sandbox, see :ref:`install-sandbox`.

docs/install/linux-macos.rst

@@ -0,0 +1,73 @@
+.. include:: ../resources.rst
+
+.. _install-linux-macos:
+
+##############################
+Installation on Linux or macOS
+##############################
+
+*****
+About
+*****
+
+The following documentation outlines the installation of PatZilla on Debian
+GNU/Linux or derivates, and macOS.
+
+We appreciate contributions in form of walkthroughs about how to
+install PatZilla on other distributions and platforms.
+
+
+*******************
+Installing PatZilla
+*******************
+
+.. _install-minimum-requirements:
+
+Minimum prerequisites
+=====================
+Foundation: MongoDB_, PDFtk_, pdfimages_ and ImageMagick_::
+
+    # Debian Linux
+    apt install mongodb-clients mongodb-server pdftk poppler-utils imagemagick unoconv
+
+    # Mac OS X
+    # https://github.com/turforlag/homebrew-cervezas
+    # https://github.com/spl/homebrew-pdftk (deprecated)
+    brew tap turforlag/homebrew-cervezas
+    brew install mongodb pdftk poppler imagemagick unoconv
+
+Python stack::
+
+    apt install python2.7 python2.7-dev python-virtualenv build-essential libxml2-dev libxslt1-dev zlib1g-dev
+
+.. note::
+
+    As PatZilla is currently being shipped as Python sdist package only, we need to have
+    some build tools and header files installed on the system before running the installation.
+    This will change as soon as Debian or other distribution packages will be available.
+
+
+Distribute & Pip
+================
+The recommended way to install PatZilla is with `pip <http://www.pip-installer.org/>`_::
+
+    pip install patzilla
+
+You might want to verify the installation actually worked::
+
+    patzilla --version
+    patzilla 0.142.5
+
+If you need an older version, please visit
+the `release history <https://pypi.org/project/patzilla/#history>`_
+of `PatZilla on PyPI <https://pypi.org/project/patzilla/>`_.
+
+
+.. tip::
+
+    As PatZilla pulls in a significant amount of Python package dependencies,
+    you might want to consider installing the software isolated from the system Python
+    by using "virtualenv" before proceeding with ``pip install patzilla``::
+
+        virtualenv --python=python2 .venv2
+        source .venv2/bin/activate

docs/install/mongodb-backup.rst

@@ -1,3 +1,5 @@
+.. include:: ../resources.rst
+
 .. _mongodb-backup:
 
 ##############