Read the Docs configuration.

.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

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.

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 <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

docs/requirements.txt

@@ -0,0 +1 @@
+Sphinx~=8.1.3

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 <ppx>`, :doc:`xp <xp>`,
    :doc:`validate <validate>`, :doc:`transform <transform>`
@@ -93,5 +96,5 @@ More XSDs and DTDs examples_ can be found in the Xul Bitbucket repository.
    <https://www.w3.org/TR/xhtml1>`_
 
 
-.. _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/