Skip to content

Commit

Permalink
More documentation; Furo theme.
Browse files Browse the repository at this point in the history
  • Loading branch information
@peteradrichem
peteradrichem committed Jan 27, 2025
1 parent 031a526 commit 1d897bd
Show file tree
Hide file tree
Showing 13 changed files with 453 additions and 355 deletions.
48 changes: 31 additions & 17 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,6 @@
Xul -- XML Utilities
====================

.. image:: https://img.shields.io/pypi/pyversions/xul.svg
:target: https://pypi.org/project/Xul/
:alt: Python versions

.. image:: https://img.shields.io/pypi/l/xul.svg
:target: https://pypi.org/project/Xul/
:alt: License

.. image:: https://img.shields.io/pypi/v/xul
:target: https://pypi.org/project/Xul/
:alt: PyPI version
Expand All @@ -18,21 +10,42 @@ Xul -- XML Utilities
:target: https://pypi.org/project/Xul/
:alt: Wheel

.. image:: https://img.shields.io/pypi/pyversions/xul.svg
:target: https://pypi.org/project/Xul/
:alt: Python versions

.. image:: https://img.shields.io/pypi/l/xul.svg
:target: https://pypi.org/project/Xul/
:alt: License

.. image:: https://readthedocs.org/projects/xul/badge/
:target: https://xul.readthedocs.io/en/stable/
:alt: Documentation

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Black code style

.. image:: https://img.shields.io/badge/type%20checked-mypy-039dfc
:target: https://mypy-lang.org
:alt: Typing checked by mypy

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
:target: https://astral.sh/ruff
:alt: Ruff linting

.. image:: https://img.shields.io/badge/imports-isort-1674b1
:target: https://pycqa.github.io/isort/
:alt: Imports sorted by isort

.. image:: https://github.com/peteradrichem/Xul/actions/workflows/code-checks.yml/badge.svg
:target: https://github.com/peteradrichem/Xul/actions/workflows/code-checks.yml
:alt: Code checks

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black

Xul is a set of XML scripts written in Python.

Xul scripts
===========
Xul is a set of XML scripts written in Python.

- ``ppx``: pretty print XML
- ``xp``: select XML nodes with XPath
Expand All @@ -41,7 +54,7 @@ Xul scripts

Installation
------------
Xul command line scripts can be installed with **pip**:
Xul command line scripts can be installed with pip:

.. code:: text
Expand Down Expand Up @@ -88,18 +101,19 @@ For example:
output filenames to standard output
-l, -f, --files-with-hits
only the names of files with a non-false and non-NaN result are written to standard output
only names of files with a result that is not false and
not NaN are written to standard output
-L, -F, --files-without-hits
only the names of files with a false or NaN result, or without any results are written to
standard output
only names of files with a false or NaN result, or without a result,
are written to standard output
namespace options:
-d DEFAULT_NS_PREFIX, --default-prefix DEFAULT_NS_PREFIX
set the prefix for the default namespace in XPath [default: 'd']
-e, --exslt add EXSLT XML namespaces
-q, --quiet don't print XML source namespaces
output options:
element output options:
-p, --pretty-element pretty print the result element
-r, --result-xpath print the XPath expression of the result element (or its parent)
Expand Down
9 changes: 0 additions & 9 deletions docs/_static/custom.css
View file

This file was deleted.

37 changes: 20 additions & 17 deletions docs/changelog.rst
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
.. _changelog:

=========
Changelog
=========

This document records all notable changes to `Xul <https://xul.readthedocs.io/>`_.

`3.0.0-rc.1 <https://github.com/peteradrichem/Xul/compare/2.5.1...py3k>`_ (2025-01-19)
--------------------------------------------------------------------------------------
`3.0.0 <https://github.com/peteradrichem/Xul/compare/2.5.1...3.0.0>`_ (2025-01-27)
==================================================================================
* Drop support for Python < 3.9.
* :doc:`xp <xp>`: fix boolean result (Python >= 3.12).
* :doc:`xp <xp>`: fix string result representation (Python 3).
Expand All @@ -19,50 +22,50 @@ This document records all notable changes to `Xul <https://xul.readthedocs.io/>`
* Test script for local testing with Docker Compose.
* Removed legacy code.
* Typing.
* Updated Sphinx configuration.
* Updated Sphinx configuration; Furo theme.
* Output formatting (f-strings).

`2.5.1 <https://github.com/peteradrichem/Xul/compare/2.5.0...2.5.1>`_ (2024-12-26)
----------------------------------------------------------------------------------
==================================================================================
* Catch UnicodeDecodeError (Python 3).

`2.5.0 <https://github.com/peteradrichem/Xul/compare/2.4.2...2.5.0>`_ (2024-12-25)
----------------------------------------------------------------------------------
==================================================================================
* Documentation updates.
* Tested on Python 3.11, 3.12, 3.13.
* :doc:`transform <transform>`: honor ``--file`` with a non-XML result.

`2.4.2 <https://github.com/peteradrichem/Xul/compare/2.4.1...2.4.2>`_ (2024-12-15)
----------------------------------------------------------------------------------
==================================================================================
* Moved to `GitHub <https://github.com/peteradrichem/Xul>`_.
* Read the Docs configuration.
* Migrated to pyproject.toml.

`2.4.1 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.4.1%0D2.4.0>`_ (2022-02-14)
----------------------------------------------------------------------------------------------
==============================================================================================
* Fixed Changelog URL.

`2.4.0 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.4.0%0D2.3.0>`_ (2022-02-14)
----------------------------------------------------------------------------------------------
==============================================================================================
* Beter handling of encodings other than UTF-8 (e.g. ISO-8859, UTF-16, UCS-2, UCS-4).
* Added ``--file FILE`` option to :doc:`transform <transform>`: save result to file.
* :doc:`transform <transform>`: now only transforms a single file.
* Added ``--xsl-output`` option to :doc:`transform <transform>`: honor ``xsl:output``.
* Removed xul.dom module (legacy).

`2.3.0 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.3.0%0D2.2.1>`_ (2021-01-28)
----------------------------------------------------------------------------------------------
==============================================================================================
* Added ``--invalidated-files`` option to :doc:`validate <validate>`: only print names of invalidated files.
* Added ``--validated-files`` option to :doc:`validate <validate>`: only print names of validated XML files.
* :doc:`xp <xp>`: ``--files-with-hits`` and ``--files-without-hits`` options are mutually exclusive.
* Consistent broken pipes ``errno.EPIPE`` exit status (Python 2).

`2.2.1 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.2.1%0D2.2.0>`_ (2021-01-14)
----------------------------------------------------------------------------------------------
==============================================================================================
* :doc:`xp <xp>` ``--pretty-element`` fix: output multiple results to a pipe (Python 2).

`2.2.0 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.2.0%0D2.1.0>`_ (2020-10-07)
----------------------------------------------------------------------------------------------
==============================================================================================
* :doc:`xp <xp>`: handle `NaN` [#NaN]_ result as a false result (``--files-with|without-hits``).
* Renamed :doc:`xp <xp>` ``--files-without-results`` option to ``--files-without-hits``: only print names of files with a false or `NaN` [#NaN]_ result, or without any results.
* Renamed :doc:`xp <xp>` ``--files-with-results`` option to ``--files-with-hits``: only print names of files with a non-false and non-`NaN` [#NaN]_ result.
Expand All @@ -71,25 +74,25 @@ This document records all notable changes to `Xul <https://xul.readthedocs.io/>`
* README: documentation is on `Read The Docs <https://xul.readthedocs.io/>`_.

`2.1.0 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.1.0%0D2.0.3>`_ (2020-09-09)
----------------------------------------------------------------------------------------------
==============================================================================================
* Added ``--quiet`` option to :doc:`xp <xp>`: don't print the XML namespace list.
* Added ``--files-without-results`` option to :doc:`xp <xp>`: only print names of files with a false result or without any results.
* Added ``--files-with-results`` option to :doc:`xp <xp>`: only print names of files with XPath matches.

`2.0.3 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.0.3%0D2.0.2>`_ (2020-06-10)
----------------------------------------------------------------------------------------------
==============================================================================================
* Fix output encoding when piping output to a pager like less (Python 2).

`2.0.2 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.0.2%0D2.0.1>`_ (2020-05-31)
----------------------------------------------------------------------------------------------
==============================================================================================
* Fix: removed encoding from Pygments formatter so highlight returns Unicode strings.

`2.0.1 <https://bitbucket.org/peteradrichem/xul/branches/compare/2.0.1%0D2.0.0>`_ (2020-03-08)
----------------------------------------------------------------------------------------------
* Added install extra "syntax" (Pygments): ``pip install Xul[syntax]``
==============================================================================================
* Added "syntax" install extra (Pygments): ``pip install Xul[syntax]``

2.0.0 (2020-03-07)
------------------
==================
Open sourced Xul.


Expand Down
17 changes: 9 additions & 8 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,14 @@
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "alabaster"
html_static_path = ["_static"]

html_theme = "furo"
html_theme_options = {
"description": "XML Utilities",
"font_size": "16px",
"code_font_size": "13px",
"fixed_sidebar": True,
"extra_nav_links": {"Index": "genindex.html"},
"source_repository": "https://github.com/peteradrichem/Xul/",
"source_branch": "main",
"source_directory": "docs/",
}
html_title = "XML Utilities"
html_short_title = "Xul"

pygments_style = "default"
pygments_dark_style = "lightbulb"
83 changes: 54 additions & 29 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@
=================
Xul documentation
=================
Xul: XML [#]_ utilities written in Python.
Current release: |release|

XML [#]_ utilities written in Python.
.. image:: https://img.shields.io/pypi/v/xul
:target: https://pypi.org/project/Xul/
:alt: PyPI version

Current version: |release|
.. image:: https://img.shields.io/pypi/wheel/xul.svg
:target: https://pypi.org/project/Xul/
:alt: Wheel

.. image:: https://img.shields.io/pypi/pyversions/xul.svg
:target: https://pypi.org/project/Xul/
Expand All @@ -13,51 +20,56 @@ Current version: |release|
:target: https://pypi.org/project/Xul/
:alt: License

.. image:: https://img.shields.io/pypi/v/xul
:target: https://pypi.org/project/Xul/
:alt: PyPI version

.. image:: https://img.shields.io/pypi/wheel/xul.svg
:target: https://pypi.org/project/Xul/
:alt: Wheel

.. image:: https://readthedocs.org/projects/xul/badge/
:target: https://xul.readthedocs.io/en/stable/
:alt: Documentation

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Black code style

.. image:: https://img.shields.io/badge/type%20checked-mypy-039dfc
:target: https://mypy-lang.org
:alt: Typing checked by mypy

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
:target: https://astral.sh/ruff
:alt: Ruff linting

.. image:: https://img.shields.io/badge/imports-isort-1674b1
:target: https://pycqa.github.io/isort/
:alt: Imports sorted by isort

.. image:: https://github.com/peteradrichem/Xul/actions/workflows/code-checks.yml/badge.svg
:target: https://github.com/peteradrichem/Xul/actions/workflows/code-checks.yml
:alt: Code checks

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black

.. index::
single: scripts

Xul scripts
-----------
Supported XML sources are documented in :ref:`xml_source`.
===========
Xul is a set of XML scripts written in Python.
The supported XML sources are documented in :ref:`xml_source`.

.. toctree::
:caption: Scripts
:maxdepth: 2

ppx
xp
validate
transform

Other
-----
.. toctree::
:maxdepth: 2

xml_source
changelog

.. index::
single: install
single: install; syntax highlighting
single: syntax highlighting; install

Installing
----------
==========
Xul command-line scripts can be installed with pip:

.. code-block:: bash
Expand All @@ -70,24 +82,37 @@ Install Xul with Pygments_ for XML syntax highlighting.
pip install Xul[syntax]
.. index::
single: install; dependencies
single: dependencies

Dependencies
------------
Xul uses the excellent lxml_ XML toolkit, a Pythonic binding for the C libraries
libxml2_ and libxslt_.

Changelog
---------
Xul :doc:`Changelog <changelog>`.

.. index::
single: source

Source
------
The source can be found on GitHub_.

Other
=====
* :ref:`xml_source`
* :ref:`changelog`
* :ref:`Xul index <genindex>`

.. toctree::
:caption: Other
:hidden:

Indices and search
------------------
* :ref:`genindex`
* :ref:`search`
xml_source
changelog
genindex


.. _lxml: https://lxml.de/
Expand Down
Loading

0 comments on commit 1d897bd

Please sign in to comment.