Adding sphinx docs

# test artefacts

.pytest_cache

docs/_build

# vscode artefacts

.vscode

# Minimal makefile for Sphinx documentation

#

# You can set these variables from the command line, and also

# from the environment for the first two.

SPHINXOPTS    ?=

SPHINXBUILD   ?= sphinx-build

SOURCEDIR     = .

BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".

help:

	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new

# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

%: Makefile

	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

# Configuration file for the Sphinx documentation builder.

#

# For the full list of built-in configuration values, see the documentation:

# https://www.sphinx-doc.org/en/master/usage/configuration.html

# 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('../src/xmltest'))

# -- Project information -----------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'xmltest'

copyright = '2024, Mark Canterbury'

author = 'Mark Canterbury'

# -- General configuration ---------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [

    'sphinx.ext.autodoc',

    'sphinx.ext.viewcode',

    'sphinx.ext.napoleon'

]

templates_path = ['_templates']

exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'

html_static_path = ['_static']

Getting started

===============

Description

------------

xmltest is a small package to help with testing XSD schema sets. Under the hood it uses the `xmlschema

library <https://pypi.org/project/xmlschema/>`_, and provides a simple interface for common tasks, namely:

- Building an XMLSchema instance from a set of XSD documents and returning any errors

- Testing instance XML documents against the schema set and returning any errors

- Provides a command-line tool for testing multiple schema sets and instance docs

Installation

------------

xmltest can be installed via pip.::

    pip install xmltest

It requires Python 3.7 or later.

Basic usage

-----------

Use the `build_schema()` function to build an XMLSchema instance from a bunch of schema files. This takes

care of building the schema location dictionary and applying different validation rules so that imported schema

files can be syntax checked before attempting to build.

.. code-block:: Python

    from xmltest import build_schema

    schema, build_results = build_schema("path_to_core_schema.xsd", ["path_to_imported_schema.xsd"])

The `build_results` returned provide a BuildResult structure for each file passed in, 

as well as an indication of whether the build succeeded or not. If it did not, `schema` will be `None`

The returned XMLSchema instance can then be used as per the XMLSchema library docs.

However, for the common case of wanting to both build a schema set and then test a bunch of instance files,

the `test_instance_docs` helper function is provided.

.. code-block:: Python

    from xmltest import build_schema, test_instance_docs

    schema, build_results = build_schema("path_to_core_schema.xsd", ["path_to_imported_schema.xsd"])

    if build_results.built_ok:

        for result in test_instance_docs(schema, ["path_to_instance_doc.xml"]):

            print (f"{result.file} OK = {result.ok}")

There is yet another helper function called `validate` that combines both `build_schema` and `test_instance_docs`

into one function call. Instead of named parameters, it accepts a dict (or a list of dicts)

which are expected to contain paths to the core schema, supporting schemas and instance docs.

.. code-block:: Python

    from xmltest import validate

    config = {

        "coreSchema" : "path_to_core_schema.xsd",

        "supportingSchemas" : ["path_to_supporting_schema.xsd"], # can be empty list if not needed

        "instanceDocs" : ["path_to_instance_doc.xml"]            # can be empty list if not needed

    }

    results = validate(config)

    # Returns a generator for each config passed in. Here, only a single

    # object is passed in, so only a single result will be returned

    for result in results:

        print(f"Core schema: {result.core_schema_path})

        print(f"Schema built OK? {result.built_ok}")

        for validation_result in validation_results:

            print(f"Instance doc: {validation_result.file} OK? {validation_result.ok}")

CLI

---

A command line tool is also provided which performs the build and validation steps based

on either command line parameters or on a JSON config file of the same format used by `validate`

::

    xmltest -c config.JSON

The tool will output the build and validation results to stdout, either in tabular form

or as JSON if the `-j` switch is used. If tabular form is used and the rich library is present,

output will be prettier. 

The tool will return:

- 0 if the build and validation steps both succeeded without errors

- if there were fatal build failures

- if there were errors in the instance document validation

As with `validate`, the JSON configuration can either contain a single dict giving

paths to a schema set and a list of instance documents to test against it, or can contain

a list of the same. This allows multiple schema sets and their instance documents to

be tested in one pass.

.. xmltest documentation master file, created by

   sphinx-quickstart on Mon Mar 25 13:25:27 2024.

   You can adapt this file completely to your liking, but it should at least

   contain the root `toctree` directive.

Welcome to xmltest's documentation!

===================================

This is cool.

.. toctree::

   :maxdepth: 2

   :caption: Contents:

   getting_started

   modules

Indices and tables

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`