Migrate documentation to Sphinx. (#89)

* Add basic Sphinx configuration. * Translate documentation to Sphinx .rst * Add doc/_build to gitignore. * Rename requirements.rst back to .txt. * Fix HTMLFormFiller reference. * Caption the toctree sections. * Switch to the RTD Sphinx theme. * Add API documentation. * Dowgrade Sphinx to 7.4 for sphinx-rtd-theme. * Update Read the Docs badge to point to genshi-edgewall.readthedocs.org.
edgewall · Aug 27, 2024 · 3b7bf4c · 3b7bf4c
1 parent dccac36
commit 3b7bf4c
Show file tree

Hide file tree

Showing 29 changed files with 285 additions and 146 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 *.egg-info
 build
 *.so
-__pycache__
+__pycache__
+doc/_build
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+#
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: doc/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: doc/requirements.txt
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@ About Genshi
 
 <!-- badges-start -->
 
-[![ReadTheDocs badge](https://readthedocs.org/projects/genshi/badge/?version=latest&style=for-the-badge)](https://genshi.readthedocs.org/)
+[![ReadTheDocs badge](https://readthedocs.org/projects/genshi-edgewall/badge/?version=latest&style=for-the-badge)](https://genshi-edgewall.readthedocs.org/)
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/edgewall/genshi/tests.yml?branch=master&style=for-the-badge)](https://github.com/edgewall/genshi/actions/workflows/tests.yml)
 [![PyPI - Version](https://img.shields.io/pypi/v/genshi?style=for-the-badge)](https://pypi.org/project/genshi/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/genshi?style=for-the-badge)](https://pypi.org/project/genshi/)

diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,20 @@
+# 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)
diff --git a/doc/api/builder.rst b/doc/api/builder.rst
@@ -0,0 +1,4 @@
+genshi.builder
+==============
+
+.. automodule:: genshi.builder
diff --git a/doc/api/compat.rst b/doc/api/compat.rst
@@ -0,0 +1,4 @@
+genshi.compat
+=============
+
+.. automodule:: genshi.compat
diff --git a/doc/api/core.rst b/doc/api/core.rst
@@ -0,0 +1,4 @@
+genshi.core
+===========
+
+.. automodule:: genshi.core
diff --git a/doc/api/filters.rst b/doc/api/filters.rst
@@ -0,0 +1,19 @@
+genshi.filters
+==============
+
+.. automodule:: genshi.filters
+
+
+genshi.filters.html
+-------------------
+.. automodule:: genshi.filters.html
+
+
+genshi.filters.i18n
+-------------------
+.. automodule:: genshi.filters.i18n
+
+
+genshi.filters.transform
+------------------------
+.. automodule:: genshi.filters.transform
diff --git a/doc/api/genshi.rst b/doc/api/genshi.rst
@@ -0,0 +1,4 @@
+genshi
+======
+
+.. automodule:: genshi
diff --git a/doc/api/input.rst b/doc/api/input.rst
@@ -0,0 +1,4 @@
+genshi.input
+============
+
+.. automodule:: genshi.input
diff --git a/doc/api/output.rst b/doc/api/output.rst
@@ -0,0 +1,4 @@
+genshi.output
+=============
+
+.. automodule:: genshi.output
diff --git a/doc/api/path.rst b/doc/api/path.rst
@@ -0,0 +1,4 @@
+genshi.path
+===========
+
+.. automodule:: genshi.path
diff --git a/doc/api/template.rst b/doc/api/template.rst
@@ -0,0 +1,52 @@
+genshi.template
+===============
+
+.. automodule:: genshi.template
+
+
+genshi.template.base
+--------------------
+
+.. automodule:: genshi.template.base
+
+
+genshi.template.directives
+--------------------------
+
+.. automodule:: genshi.template.directives
+
+
+genshi.template.eval
+--------------------
+
+.. automodule:: genshi.template.eval
+
+
+genshi.template.interpolation
+-----------------------------
+
+.. automodule:: genshi.template.interpolation
+
+
+genshi.template.loader
+----------------------
+
+.. automodule:: genshi.template.loader
+
+
+genshi.template.markup
+----------------------
+
+.. automodule:: genshi.template.markup
+
+
+genshi.template.plugin
+----------------------
+
+.. automodule:: genshi.template.plugin
+
+
+genshi.template.text
+--------------------
+
+.. automodule:: genshi.template.text
diff --git a/doc/api/util.rst b/doc/api/util.rst
@@ -0,0 +1,4 @@
+genshi.util
+===========
+
+.. automodule:: genshi.util
diff --git a/doc/conf.py b/doc/conf.py
@@ -0,0 +1,40 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Genshi"
+copyright = "2024, Edgewall Software"
+author = "Edgewall Software"
+release = "0.8"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+modindex_common_prefix = ["genshi."]
+autodoc_default_options = {
+    "members": True,
+}
+autodoc_preserve_defaults = True
+
+# -- 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"]
+html_theme_options = {
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+}
diff --git a/doc/filters.txt → doc/filters.rst b/doc/filters.txt → doc/filters.rst
@@ -4,16 +4,12 @@
 Stream Filters
 ==============
 
-`Markup Streams`_ showed how to write filters and how they are applied to
+:doc:`streams` showed how to write filters and how they are applied to
 markup streams. This page describes the features of the various filters that
 come with Genshi itself.
 
-.. _`Markup Streams`: streams.html
-
-.. contents:: Contents
-   :depth: 1
-.. sectnum::
 
+.. _HTMLFormFiller:
 
 HTML Form Filler
 ================

diff --git a/doc/i18n.txt → doc/i18n.rst b/doc/i18n.txt → doc/i18n.rst
@@ -19,11 +19,6 @@ a plugin.
 .. _`babel`: http://babel.edgewall.org/
 
 
-.. contents:: Contents
-   :depth: 2
-.. sectnum::
-
-
 Basics
 ======
 

diff --git a/doc/index.rst b/doc/index.rst
@@ -0,0 +1,48 @@
+.. -*- mode: rst; encoding: utf-8 -*-
+
+=======
+Preface
+=======
+
+.. image:: logo.png
+   :width: 225
+   :height: 81
+   :align: center
+   :alt: Genshi - Generate output for the web
+   :class: logo
+
+--------------------------------------------
+Toolkit for generation of output for the web
+--------------------------------------------
+
+Genshi is a Python library that provides an integrated set of components
+for parsing, generating, and processing HTML, XML or other textual content
+for output generation on the web. The major feature is a template language,
+which is heavily inspired by Kid.
+
+.. toctree::
+  :caption: Installation
+
+  install
+  upgrade
+
+
+.. toctree::
+  :caption: Usage
+
+  streams
+  templates
+  xml-templates
+  text-templates
+  loader
+  filters
+  xpath
+  i18n
+  plugin
+
+
+.. toctree::
+  :caption: API Documentation
+  :glob:
+
+  api/*
diff --git a/doc/index.txt b/doc/index.txt
diff --git a/doc/install.txt → doc/install.rst b/doc/install.txt → doc/install.rst
@@ -2,11 +2,6 @@ Installing Genshi
 =================
 
 
-.. contents:: Contents
-   :depth: 2
-.. sectnum::
-
-
 Prerequisites
 -------------
 

diff --git a/doc/loader.txt → doc/loader.rst b/doc/loader.txt → doc/loader.rst
@@ -10,10 +10,6 @@ templates so they do not need to be reparsed when used, support for multiple
 template directories that together form a virtual search path, as well as
 support for different template loading strategies.
 
-.. contents:: Contents
-   :depth: 3
-.. sectnum::
-
 
 -----
 Usage

diff --git a/doc/plugin.txt → doc/plugin.rst b/doc/plugin.txt → doc/plugin.rst
@@ -8,16 +8,9 @@ While you can easily use Genshi templating through the APIs provided directly
 by Genshi, in some situations you may want to use Genshi through the template
 engine plugin API. Note though that this considerably limits the power and
 flexibility of Genshi templates (for example, there's no good way to use filters
-such as Genshi's `HTMLFormFiller`_ when the plugin
+such as Genshi's :ref:`HTMLFormFiller` when the plugin
 API is sitting between your code and Genshi).
 
-.. _`HTMLFormFiller`: filters.html>#html-form-filler
-
-
-.. contents:: Contents
-   :depth: 2
-.. sectnum::
-
 
 Introduction
 ============

diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -0,0 +1,2 @@
+sphinx==7.4.7
+sphinx-rtd-theme==2.0.0
diff --git a/doc/streams.txt → doc/streams.rst b/doc/streams.txt → doc/streams.rst
@@ -7,11 +7,6 @@ Markup Streams
 A stream is the common representation of markup as a *stream of events*.
 
 
-.. contents:: Contents
-   :depth: 2
-.. sectnum::
-
-
 Basics
 ======