Add HTML docs and expand docs

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  commands:
+    # https://docs.readthedocs.com/platform/stable/build-customization.html#install-dependencies-with-uv
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv run --group docs sphinx-build -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html

README.md

@@ -2,16 +2,15 @@
 
 > [!NOTE]
 > **In early development!**
-> Expect bugs, missing features, and incomplete documentation.
-> Docstub is still evaluating which features it needs to support as the community gives feedback.
-> Several features are experimental and included to make adoption of docstub easier.
-> Long-term, some of these might be discouraged or removed as docstub matures.
+> Docstub is not feature-complete or thoroughly tested yet.
+> Its behavior, configuration or command line interface may change significantly between releases.
 
-docstub is a command-line tool to generate [Python stub files](https://typing.python.org/en/latest/guides/writing_stubs.html) (i.e., PYI files) from type descriptions found in [numpydoc](https://numpydoc.readthedocs.io)-style docstrings.
+docstub is a command-line tool to generate [Python stub files](https://typing.python.org/en/latest/guides/writing_stubs.html).
+It extracts necessary type information from [NumPyDoc style](https://numpydoc.readthedocs.io) docstrings.
 
 Many packages in the scientific Python ecosystem already describe expected parameter and return types in their docstrings.
 Docstub aims to take advantage of these and help with the adoption of type annotations.
-It does so by supporting widely used readable conventions such as `array of dtype` or `iterable of int(s)` which it translates into valid type annotations.
+It does so by supporting widely used readable conventions such as `array of dtype` or `iterable of int(s)` which are translated into valid type annotations.
 
 
 ## Installation & getting started

docs/command_line.md

@@ -1,11 +1,14 @@
-# Command line reference
+# Command line
 
-## Command `docstub`
+The reference for docstub's command line interface.
+It uses [Click](https://click.palletsprojects.com/en/stable/), so [shell completion](https://click.palletsprojects.com/en/stable/shell-completion/) can be enabled.
+
+## `docstub`
 
 <!--- The following block is checked by the test suite --->
 <!--- begin cli-docstub --->
 
-```plain
+```none
 Usage: docstub [OPTIONS] COMMAND [ARGS]...
 
   Generate Python stub files from docstrings.
@@ -22,12 +25,12 @@ Commands:
 <!--- end cli-docstub --->
 
 
-## Command `docstub run`
+## `docstub run`
 
 <!--- The following block is checked by the test suite --->
 <!--- begin cli-docstub-run --->
 
-```plain
+```none
 Usage: docstub run [OPTIONS] PACKAGE_PATH
 
   Generate Python stub files.
@@ -66,12 +69,12 @@ Options:
 <!--- end cli-docstub-run --->
 
 
-## Command `docstub clean`
+## `docstub clean`
 
 <!--- The following block is checked by the test suite --->
 <!--- begin cli-docstub-clean --->
 
-```plain
+```none
 Usage: docstub clean [OPTIONS]
 
   Clean the cache.

docs/conf.py

@@ -0,0 +1,73 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from datetime import date
+
+# -- Project information ------------------------------------------------------
+
+project = "docstub"
+copyright = f"{date.today().year}, docstub contributors"
+
+templates_path = ["templates"]
+
+
+# -- Extension configuration --------------------------------------------------
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    # https://numpydoc.readthedocs.io/
+    "myst_parser",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "typing": ("https://typing.python.org/en/latest/", None),
+}
+
+myst_enable_extensions = [
+    # Enable fieldlist to allow for Field Lists like in rST (e.g., :orphan:)
+    "fieldlist",
+    # Enable fencing directives with `:::`
+    "colon_fence",
+]
+
+myst_heading_anchors = 3
+
+
+# -- HTML output --------------------------------------------------------------
+
+html_theme = "furo"
+
+html_static_path = ["static"]
+
+html_css_files = ["furo_overrides.css"]
+
+html_title = "docstub docs"
+
+html_theme_options = {
+    "light_css_variables": {
+        # Make font less harsh on light theme
+        "color-foreground-primary": "#363636",
+        "color-announcement-background": "var(--color-admonition-title-background--important)",
+        "color-announcement-text": "var(--color-content-foreground)",
+        "admonition-font-size": "var(--font-size--normal)",
+    },
+    "dark_css_variables": {
+        "color-announcement-background": "var(--color-admonition-title-background--important)",
+    },
+    "announcement": "<b>🧪 In early development!</b> API and behavior may break between releases.",
+}
+
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "external-links.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+        "sidebar/variant-selector.html",
+    ]
+}

docs/configuration.md

@@ -1,15 +1,17 @@
-# Configuration reference
+# Configuration files
 
-Docstub will automatically look for configuration in files named
+Docstub will automatically look for configuration files in the current directory.
+These files must be named
 
-- `pyproject.toml`, and
+- `pyproject.toml`
 - `docstub.toml`
 
-in the current working directory.
-If config files are explicitly passed to the command line interface via the `--config` option, docstub won't look implicitly look for files in the current directory.
-Multiple configuration files can be used, whose content will be merged.
+Alternatively, config files can also be passed in the command line with the `--config` option.
+In this case, docstub will not look for configuration files in the current directory.
+When multiple configuration files are passed explicitly, their content is merged.
 
-Out of the box, docstub makes use of an internal configuration file [`numpy_config.toml`](../src/docstub/numpy_config.toml) which provides defaults to use NumPy types.
+Out of the box, docstub makes use of an internal configuration files are always loaded.
+One such file is [`numpy_config.toml`](../src/docstub/numpy_config.toml) which provides defaults for NumPy types.
 
 
 ## Configuration fields in `[tool.docstub]`
@@ -19,7 +21,7 @@ All configuration must be declared inside a `[tool.docstub]` table.
 
 ### `ignore_files`
 
-- [TOML type](https://toml.io/en/latest): array of string(s)
+[TOML type](https://toml.io/en/latest): array of string(s)
 
 Ignore files and directories matching these [glob-style patterns](https://docs.python.org/3/library/glob.html#glob.translate).
 Patterns that don't start with "/" are interpreted as relative to the
@@ -39,7 +41,7 @@ ignore_files = [
 
 ### `types`
 
-- [TOML type](https://toml.io/en/latest): table, mapping string to string
+[TOML type](https://toml.io/en/latest): table, mapping string to string
 
 Types and their external modules to use in docstrings.
 Docstub can't yet automatically discover where to import types from other packages from.
@@ -60,7 +62,7 @@ NDArray = "numpy.typing"
 
 ### `type_prefixes`
 
-- [TOML type](https://toml.io/en/latest): table, mapping string to string
+[TOML type](https://toml.io/en/latest): table, mapping string to string
 
 Prefixes for external modules to match types in docstrings.
 Docstub can't yet automatically discover where to import types from other packages from.
@@ -81,7 +83,7 @@ plt = "matplotlib.pyplot
 
 ### `type_nicknames`
 
-- [TOML type](https://toml.io/en/latest): table, mapping string to string
+[TOML type](https://toml.io/en/latest): table, mapping string to string
 
 Nicknames for types that can be used in docstrings to describe valid Python types or annotations.
 
@@ -90,6 +92,8 @@ Example:
 ```toml
 [tool.docstub.type_nicknames]
 func = "Callable"
+buffer = "collections.abc.Buffer"
 ```
 
-- Will map `func` to the `Callable` type from the `typing` module.
+- Will map `func` to the `Callable`.
+- Will map `buffer` to `collections.abc.Buffer`.

docs/glossary.md

@@ -0,0 +1,24 @@
+# Glossary
+
+This section defines central terms used in this documentation.
+
+:::{glossary}
+:sorted:
+
+doctype
+    A type description of a type in a docstring, such as of a parameter, return value, or attribute.
+    Any {term}`annotation expression` is valid as a doctype, but doctypes support an [extended syntax](typing_syntax.md) with natural language variants.
+
+type name
+    The name of a single (atomic) type.
+    A type name can include a {term}`type prefix`.
+    An {term}`annotation expression` can contain multiple typen names.
+    For example, the annotation expression `collections.abc.Iterable[int or float]` consists of the three names `collections.abc.Iterable`, `int` and `float`.
+
+type prefix
+    A dot-delimited prefix that is part of a {term}`type name`.
+    The prefix can describe the full path of a type or consist of an alias.
+    For example, `collections.abc.Iterable` has the type prefix `collections.abc`.
+    `np.int` has the prefix `np` which may be an alias for `numpy`.
+    [Type prefixes can be defined in the configuration](configuration.md#type_prefixes) or are inferred by docstub from import statements it can see.
+:::

docs/index.md

@@ -0,0 +1,35 @@
+# docstub documentation
+
+:::{admonition} In early development!
+:class: important
+
+Docstub is not feature-complete or thoroughly tested yet.
+Its behavior, configuration or command line interface may change significantly between releases.
+:::
+
+docstub is a command-line tool to generate [Python stub files](https://typing.python.org/en/latest/spec/distributing.html#stub-files).
+It extracts necessary type information from [NumPyDoc style](https://numpydoc.readthedocs.io) docstrings.
+
+Many packages in the scientific Python ecosystem already describe expected parameter and return types in their docstrings.
+Docstub aims to take advantage of these and help with the adoption of type annotations.
+It does so by supporting widely used readable conventions such as `array of dtype` or `iterable of int(s)` which are translated into valid type annotations.
+
+---
+
+:::{toctree}
+:caption: User guides
+:maxdepth: 1
+
+introduction
+:::
+
+:::{toctree}
+:caption: Reference
+:maxdepth: 1
+
+command_line
+configuration
+typing_syntax
+glossary
+release_notes/index
+:::