From 32416db5a78d436bf1ede28a9faab2f01f33681d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 29 Aug 2025 19:58:41 +0200 Subject: [PATCH] Draft HTML docs with Sphinx, Furo & myst parser --- docs/command_line.md | 6 +-- docs/conf.py | 63 ++++++++++++++++++++++ docs/index.md | 36 +++++++++++++ docs/{user_guide.md => introduction.md} | 18 ++++--- docs/release_notes/index.md | 9 ++++ docs/release_notes/v0.2.0.md | 2 +- docs/templates/sidebar/external-links.html | 6 +++ docs/typing_syntax.md | 14 ++--- pyproject.toml | 17 ++++-- src/docstub/__init__.py | 6 +-- 10 files changed, 151 insertions(+), 26 deletions(-) create mode 100644 docs/conf.py create mode 100644 docs/index.md rename docs/{user_guide.md => introduction.md} (94%) create mode 100644 docs/release_notes/index.md create mode 100644 docs/templates/sidebar/external-links.html diff --git a/docs/command_line.md b/docs/command_line.md index 7f73047..e2a0982 100644 --- a/docs/command_line.md +++ b/docs/command_line.md @@ -5,7 +5,7 @@ -```plain +```none Usage: docstub [OPTIONS] COMMAND [ARGS]... Generate Python stub files from docstrings. @@ -27,7 +27,7 @@ Commands: -```plain +```none Usage: docstub run [OPTIONS] PACKAGE_PATH Generate Python stub files. @@ -66,7 +66,7 @@ Options: -```plain +```none Usage: docstub clean [OPTIONS] Clean the cache. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9f1cb47 --- /dev/null +++ b/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": """ + + + + """, + "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", +] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3e9296e --- /dev/null +++ b/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 +::: diff --git a/docs/user_guide.md b/docs/introduction.md similarity index 94% rename from docs/user_guide.md rename to docs/introduction.md index e6d72e7..ec15a03 100644 --- a/docs/user_guide.md +++ b/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. diff --git a/docs/release_notes/index.md b/docs/release_notes/index.md new file mode 100644 index 0000000..16997f0 --- /dev/null +++ b/docs/release_notes/index.md @@ -0,0 +1,9 @@ +# Release notes + +:::{toctree} +:maxdepth: 1 + +v0.4.0 +v0.3.0 +v0.2.0 +::: diff --git a/docs/release_notes/v0.2.0.md b/docs/release_notes/v0.2.0.md index 43f0859..8a43202 100644 --- a/docs/release_notes/v0.2.0.md +++ b/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: diff --git a/docs/templates/sidebar/external-links.html b/docs/templates/sidebar/external-links.html new file mode 100644 index 0000000..5e86eb6 --- /dev/null +++ b/docs/templates/sidebar/external-links.html @@ -0,0 +1,6 @@ +
+

Links

+ +
\ No newline at end of file diff --git a/docs/typing_syntax.md b/docs/typing_syntax.md index 4849ccb..bd071dc 100644 --- a/docs/typing_syntax.md +++ b/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). diff --git a/pyproject.toml b/pyproject.toml index 18be2a1..723b95a 100644 --- a/pyproject.toml +++ b/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] diff --git a/src/docstub/__init__.py b/src/docstub/__init__.py index 17da713..85f19b2 100644 --- a/src/docstub/__init__.py +++ b/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__