WIP: Implementing a metadatavalidator for <meta> tags

python-scripts/metadatavalidator/.gitignore

@@ -0,0 +1,177 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env*
+.venv*
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+
+#### Specific to this project

python-scripts/metadatavalidator/README.rst

@@ -0,0 +1,201 @@
+Metadata validator for DocBook
+==============================
+
+The script in this directory check several metadata definition for DocBook.
+Metadata can be found in the ``<meta>`` and ``<info>`` tags.
+
+
+Requirements
+------------
+
+* lxml (the more recent, the better)
+* Python >=3.11 (only due to for installing with :file:`pyproject.toml`.)
+
+
+Preparing the environment
+-------------------------
+
+It's recommended to create a Python virtual environment first before you
+proceed further. The virtual environment is a self-contained Python environment
+that separates the dependencies from the system Python installation.
+
+To create a virtual environment, execute the following steps:
+
+1. Create a virtual environment with Python 3.11:
+
+    .. code-block:: bash
+
+        $ python3.11 -m venv .venv311
+
+1. Activate the virtual environment:
+
+    .. code-block:: bash
+
+        $ source .venv311/bin/activate
+
+    Your prompt changes to show the active virtual environment:
+
+    .. code-block:: bash
+
+        (.venv311) $
+
+1. Upgrade the package manager ``pip`` and ``setuptools`` to the latest version:
+
+    .. code-block:: bash
+
+        (.venv311) $ pip install --upgrade pip setuptools
+
+This makes your virtual environment ready for the next steps.
+
+If you don't need the virtual environment anymore, you can deactivate it:
+
+.. code-block:: bash
+
+    (.venv311) $ deactivate
+
+
+
+Installing the script
+---------------------
+
+Before you install the script, your current directory must be
+`python-scripts/metadatavalidator/`.
+To install the script, run the following command:
+
+.. code-block:: bash
+
+    $ pip install .
+
+
+For development, install the script in "editable" mode:
+
+.. code-block:: bash
+
+    $ pip install -e .[test]
+
+
+Setting the configuration
+-------------------------
+
+Before you call the script, check the values in the configuration file.
+The configuration file is an INI file and is searched in the following order (from highest to lowest):
+
+* Command line with :option:`--config`. This doesn't search for other configuration files.
+* Environment variable :envar:`METAVALIDATOR_CONFIG`.
+* In the current directory: :file:`metadatavalidator.ini`
+* In the users' home directory: :file:`~/.config/metadatavalidator/config.ini`
+* In the system: :file:`/etc/metadatavalidator/config.ini`
+
+The configuration file is a standard INI file.
+All boolean values are case-insensitive and can be ``true``/``yes``, ``on``/``off`` or ``0``/``1``.
+Everything else is considered as ``false``.
+List values are separated by commas.
+
+All config files are merged together. If a key is defined in multiple files,
+the last one wins. This way you can have a global configuration in the
+system directory and a local one in the current directory.
+
+
+Calling the script
+------------------
+
+Call the script with the following command:
+
+.. code-block:: bash
+
+    $ metadatavalidator PATH_TO_DOCBOOK_FILES
+
+The script will show all problems with metadata:
+
+.. code-block::
+
+    $ metadatavalidator a.xml b.xml
+    ==== RESULTS ====
+    [1] a.xml:
+      1.1: check_info_revhistory_revision: Missing recommended attribute in /d:article/d:info[2]/d:revhistory[12]/d:revision/@xml:id
+
+    [2] b.xml:
+      2.1: check_meta_task: Invalid value in metadata Unknown task(s) {'Clusering'}. Allowed are ...
+
+The output shows:
+
+* The filename.
+* The name of the check that the script executed and failed.
+* A description of the problem.
+* In some cases a line number.
+
+
+If wanted, you can add your own configuration file with the option :option:`--config`:
+
+.. code-block:: bash
+
+    $ metadatavalidator --config /path/to/config.ini PATH_TO_DOCBOOK_FILES
+
+For machine readable output of the result, use the option :option:`--format`:
+
+.. code-block:: bash
+
+    $ metadatavalidator --format json PATH_TO_DOCBOOK_FILES
+
+
+Configuration
+-------------
+
+The configuration file is search in the following order (first is the highest):
+
+1. Command line with :option:`--config`. This doesn't search for other configuration files.
+
+1. Environment variable :envar:`METAVALIDATOR_CONFIG`.
+
+1. In the current directory: :file:`metadatavalidator.ini`
+
+1. In the users' home directory: :file:`~/.config/metadatavalidator/config.ini`
+
+1. In the system: :file:`/etc/metadatavalidator/config.ini`
+
+
+Configuration values
+--------------------
+
+The following values are recognized:
+
+* :var:`validator`: Global options to configure the validator.
+    * :var:`file_extension`: The file extension to search for. Default is
+      ``.xml``.
+
+    * :var:`check_root_elements`: List of allowed root elements (space separated by local DocBook name). Default is ``assembly article book topic``.
+
+    * :var:`valid_languages`: List of valid languages (space separated by ISO 639-1 code). Default is ``ar-ar cs-cz de-de en-us es-es fr-fr hu-hu it-it ja-jp ko-kr nl-nl pl-pl pt-br ru-ru sv-se zh-cn zh-tw``.
+
+* :var:`metadata`: Options to change behaviour of specific `<meta>` tags.
+    * :var:`require_revhistory`: Requires a ``<revhistory>`` tag or not.
+
+    * :var:`require_xmlid_on_revision`:  Requires a ``xml:id`` attribute on each ``<revision>`` tag or not.
+
+    * :var:`require_meta_title`: Requires a ``<meta name="title">`` tag or not.
+
+    * :var:`meta_title_length`: Checks the length of the text content in ``<meta name="title">``. Default is 55.
+
+    * :var:`require_meta_description`: Requires a ``<meta name="description">`` tag or not.
+
+    * :var:`meta_description_length`: Checks the length of the text content in ``<meta name="description">``. Default is 155.
+
+    * :var:`require_meta_series`: Requires a ``<meta name="series">`` tag or not.
+
+    * :var:`valid_meta_series`: Lists the valid series names for ``<meta name="series">``.
+
+    * :var:`require_meta_techpartner`: Requires a ``<meta name="techpartner">`` tag or not.
+
+    * :var:`require_meta_platform`: Requires a ``<meta name="platform">`` tag or not.
+
+    * :var:`require_meta_architecture`: Requires a ``<meta name="architecture">`` tag or not.
+
+    * :var:`valid_meta_architectures`: Lists the valid architecture names for ``<meta name="architecture">/<phrase>``.
+
+    * :var:`require_meta_category`: Requires a ``<meta name="category">`` tag or not.
+
+    * :var:`valid_meta_categories`: Lists the valid category names for ``<meta name="category">/<phrase>``.
+
+    * :var:`require_meta_task`: Requires a ``<meta name="task">`` tag or not.
+
+    * :var:`valid_meta_tasks`: Lists the valid task names for ``<meta name="task">/<phrase>``.

python-scripts/metadatavalidator/metadatavalidator.code-workspace

@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {}
+}