Add HTML docs

docs/command_line.md

@@ -5,7 +5,7 @@
 <!--- 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.
@@ -27,7 +27,7 @@ Commands:
 <!--- 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,7 +66,7 @@ Options:
 <!--- 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,63 @@
+# 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 team"
+
+templates_path = ["templates"]
+
+# -- General configuration ----------------------------------------------------
+
+extensions = [
+    "numpydoc",
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+
+# -- HTML output --------------------------------------------------------------
+
+html_theme = "furo"
+
+html_title = "docstub docs"
+
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "docstub's sources on GitHub",
+            "url": "https://github.com/scientific-python/docstub",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+}
+
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/external-links.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+    ]
+}
+
+
+# -- MyST parser extension ----------------------------------------------------
+
+myst_enable_extensions = [
+    # Enable fieldlist to allow for Field Lists like in rST (e.g., :orphan:)
+    "fieldlist",
+    # Enable fencing directives with `:::`
+    "colon_fence",
+]

docs/index.md

@@ -0,0 +1,36 @@
+# docstub documentation
+
+:::{admonition} In early development!
+:class: tip
+
+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 a command-line tool to generate [Python stub files](https://typing.python.org/en/latest/guides/writing_stubs.html) from type descriptions found in [numpydoc](https://numpydoc.readthedocs.io)-style 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.
+
+
+:::{toctree}
+:caption: User guides
+:maxdepth: 1
+:hidden:
+
+introduction
+:::
+
+:::{toctree}
+:caption: Reference
+:maxdepth: 1
+:hidden:
+
+command_line
+configuration
+typing_syntax
+release_notes/index
+:::

docs/user_guide.md → docs/introduction.md

@@ -1,11 +1,13 @@
-# User guide
+# Introduction
 
-> [!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.
+:::{admonition} In early development!
+:class: tip
+
+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.
+:::
 
 
 ## Installation
@@ -19,7 +21,7 @@ pip install docstub
 In case you want to check out an unreleased version you can install directly from the repository with:
 
 ```shell
-pip install docstub @ git+https://github.com/scientific-python/docstub'
+pip install 'docstub @ git+https://github.com/scientific-python/docstub'
 ```
 
 To pin to a specific commit you can append `@COMMIT_SHA` to the repository URL above.

docs/release_notes/index.md

@@ -0,0 +1,9 @@
+# Release notes
+
+:::{toctree}
+:maxdepth: 1
+
+v0.4.0
+v0.3.0
+v0.2.0
+:::

docs/release_notes/v0.2.0.md

@@ -1,4 +1,4 @@
-## docstub 0.2.0
+# docstub 0.2.0
 
 A first prototype of the tool with the following features:
 

docs/templates/sidebar/external-links.html

@@ -0,0 +1,6 @@
+<div class="sidebar-tree">
+  <p class="caption" role="heading"><span class="caption-text">Links</span></p>
+  <ul>
+    <li class="toctree-l1"><a class="reference internal" href="https://github.com/scientific-python/docstub">Source code</a></li>
+  </ul>
+</div>

docs/typing_syntax.md

@@ -1,11 +1,13 @@
 # Typing syntax in docstrings
 
-> [!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.
+:::{admonition} In early development!
+:class: tip
+
+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 defines its own [grammar](../src/docstub/doctype.lark) to parse and transform type information in docstrings (doctypes) into valid Python type expressions.
 This grammar fully supports [Python's conventional typing syntax](https://typing.python.org/en/latest/index.html).

pyproject.toml

@@ -48,16 +48,25 @@ docstub = "docstub.__main__:cli"
 
 
 [dependency-groups]
-dev = [
-    "pre-commit >=4.3.0",
-    "ipython",
-]
 test = [
     "pytest >=8.4.1",
     "pytest-cov >= 5.0.0",
     "mypy >=1.17.0",
     "basedpyright >=1.31",
 ]
+docs = [
+    "sphinx",
+    "furo",
+    "numpydoc",
+    "myst-parser",
+    "sphinx-copybutton",
+]
+dev = [
+    {include-group = "test"},
+    {include-group = "docs"},
+    "pre-commit >=4.3.0",
+    "ipython",
+]
 
 
 [tool.setuptools_scm]

src/docstub/__init__.py

@@ -1,8 +1,6 @@
-"""
-Copyright (c) 2024 Lars Grüter. All rights reserved.
+# Copyright (c) 2024 Lars Grüter. All rights reserved.
 
-docstub: Generate Python stub files (PYI) from docstrings
-"""
+"""Generate Python stub files (PYI) from docstrings."""
 
 from ._version import __version__