diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..6075afc --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,24 @@ +# Read the Docs configuration file for Sphinx projects. +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +# Python requirements required to build the documentation. +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: . + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + builder: html + configuration: docs/conf.py + # Fail on all warnings to avoid broken references + fail_on_warning: true diff --git a/docs/conf.py b/docs/conf.py index 3199a2c..8c5695c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,8 +12,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys import os +import sys from datetime import datetime # If extensions (or modules to document with autodoc) are in another directory, @@ -39,7 +39,7 @@ # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = {".rst": "restructuredtext"} # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -48,9 +48,9 @@ master_doc = 'index' # General information about the project. -project = u'Xul' -copyright = u'%d, Peter Adrichem' % datetime.now().year -author = u'Peter Adrichem' +project = "Xul" +copyright = f"2013-{datetime.now().year}, Peter Adrichem" +author = "Peter Adrichem" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -66,7 +66,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -240,8 +240,8 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'Xul.tex', u'Xul Documentation', - u'Peter Adrichem', 'manual'), + (master_doc, "Xul.tex", "Xul Documentation", + "Peter Adrichem", "manual"), ] # The name of an image file (relative to this directory) to place at the top of @@ -270,7 +270,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'xul', u'Xul Documentation', + (master_doc, "xul", "Xul Documentation", [author], 1) ] @@ -284,9 +284,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'Xul', u'Xul Documentation', - author, 'Xul', 'One line description of project.', - 'Miscellaneous'), + (master_doc, "Xul", "Xul Documentation", + author, "Xul", "One line description of project.", + "Miscellaneous"), ] # Documents to append as an appendix to all manuals. diff --git a/docs/index.rst b/docs/index.rst index 3dc64b2..8c17a47 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,6 +26,8 @@ Current version: |release| Xul scripts ----------- +The supported XML sources are documented in :ref:`xml_source`. + .. toctree:: :maxdepth: 2 @@ -68,7 +70,7 @@ Xul :doc:`Changelog `. Source ------ -The source can be found on Bitbucket_. +The source can be found on GitHub_. Indices and search @@ -78,10 +80,10 @@ Indices and search .. _lxml: https://lxml.de/ -.. _libxml2: http://www.xmlsoft.org/ -.. _libxslt: http://xmlsoft.org/libxslt/ +.. _libxml2: https://gitlab.gnome.org/GNOME/libxml2/-/wikis/ +.. _libxslt: https://gitlab.gnome.org/GNOME/libxslt/-/wikis/ .. _Pygments: https://pygments.org/ -.. _Bitbucket: https://bitbucket.org/peteradrichem/xul +.. _GitHub: https://github.com/peteradrichem/Xul .. rubric:: Footnotes diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c380044 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +Sphinx~=8.1.3 diff --git a/docs/xml_source.rst b/docs/xml_source.rst index b312f92..90df7db 100644 --- a/docs/xml_source.rst +++ b/docs/xml_source.rst @@ -8,7 +8,7 @@ XML source ========== The Xul scripts require an XML source to operate on. -An XML source can be a local file, an URL or a pipe. +An XML source can be a local file, an URL (HTTP or FTP) or a pipe. .. index:: @@ -26,6 +26,7 @@ With ``xp`` you can select nodes in a local XML file with an XPath expression: .. index:: single: redirected output single: pipe + single: curl Pipe ---- @@ -38,6 +39,8 @@ Redirect output (pipe) to a Xul script: .. index:: single: URL + single: HTTP + single: FTP URL --- @@ -48,20 +51,20 @@ For example, to pretty print an RSS feed: ppx http://feeds.launchpad.net/pytz/announcements.atom +.. index:: + single: HTTPS + Loading XML through HTTPS is not supported and will result in an *failed to load external entity* error. +Try redirecting the HTTPS URL output to an Xul script. See the ``curl`` example above. - +Examples +======== .. index:: single: XHTML -XHTML -===== - XHTML [#]_ is part of the family of XML markup languages. It's obsolete. -Examples --------- Pretty print an XHTML document: .. code-block:: bash @@ -79,9 +82,9 @@ Print the link destinations in an XHTML document: .. code-block:: bash - xp -d html "//html:link/@href" http://www.w3.org/1999/xhtml/ + curl -s https://www.w3.org/1999/xhtml/ | xp -d html "//html:link/@href" -More XSDs and DTDs examples_ can be found in the Xul Bitbucket repository. +More XSDs and DTDs examples_ can be found in the Xul GitHub repository. .. seealso:: Xul scripts: :doc:`ppx `, :doc:`xp `, :doc:`validate `, :doc:`transform ` @@ -93,5 +96,5 @@ More XSDs and DTDs examples_ can be found in the Xul Bitbucket repository. `_ -.. _examples: https://bitbucket.org/peteradrichem/xul/src/master/examples/ -.. _libxml2: http://www.xmlsoft.org/ +.. _examples: https://github.com/peteradrichem/Xul/tree/main/examples +.. _libxml2: https://gitlab.gnome.org/GNOME/libxml2/-/wikis/