Set up for Python documentation (including front page)#187
Merged
Conversation
…on awkward1 -> awkward. Last commit before moving Python to Sphinx.
… the fly, and call sphinx.ext.napoleon directly.
Member
Author
|
I've tested it on ReadTheDocs and all is well. Now I just need to write that documentation. |
jpivarski
changed the title
Member
Author
|
I'm going to close this PR off now because it's really about the front page documentation. The next PR will be about Python docstrings. |
TaiSakuma
added a commit
to TaiSakuma/awkward
that referenced
this pull request
Apr 3, 2026
When prepare_docstrings.py was developed in 2020 (scikit-hep#187, scikit-hep#158), there was no standard Sphinx solution for generating API docs without importing the package. The script used ast to parse source files and called napoleon directly, then applied regex-based post-processing to indent RST directives. This post-processing handles specific RST constructs (:param, :type, :returns, :raises) but not others. Adding Google-style summary lines to docstrings (scikit-hep#3946) exposed this gap: summary lines were not indented inside the py:function directive, breaking the parameter rendering. sphinx-autoapi, which parses source via astroid without importing, is now available as a standard Sphinx extension. It lets Sphinx parse the generated RST natively, avoiding the need for regex-based post-processing. This commit replaces prepare_docstrings.py with sphinx-autoapi: - Add sphinx-autoapi and napoleon extensions - Monkey-patch output paths to preserve existing ak.* URL structure - Custom Jinja templates for display names and GitHub source links - Docstring filter for cross-references, backtick escaping, and member links - Skip internal submodules that collide on case-insensitive filesystems Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
TaiSakuma
added a commit
to TaiSakuma/awkward
that referenced
this pull request
Apr 3, 2026
When prepare_docstrings.py was developed in 2020 (scikit-hep#187, scikit-hep#158), there was no standard Sphinx solution for generating API docs without importing the package. The script used ast to parse source files and called napoleon directly, then applied regex-based post-processing to indent RST directives. This post-processing handles specific RST constructs (:param, :type, :returns, :raises) but not others. Adding Google-style summary lines to docstrings (scikit-hep#3946) exposed this gap: summary lines were not indented inside the py:function directive, breaking the parameter rendering. sphinx-autoapi, which parses source via astroid without importing, is now available as a standard Sphinx extension. It lets Sphinx parse the generated RST natively, avoiding the need for regex-based post-processing. This commit replaces prepare_docstrings.py with sphinx-autoapi: - Add sphinx-autoapi and napoleon extensions - Monkey-patch output paths to preserve existing ak.* URL structure - Custom Jinja templates for display names and GitHub source links - Docstring filter for cross-references, backtick escaping, and member links - Skip internal submodules that collide on case-insensitive filesystems Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
TaiSakuma
added a commit
to TaiSakuma/awkward
that referenced
this pull request
Apr 6, 2026
When prepare_docstrings.py was developed in 2020 (scikit-hep#187, scikit-hep#158), there was no standard Sphinx solution for generating API docs without importing the package. The script used ast to parse source files and called napoleon directly, then applied regex-based post-processing to indent RST directives. This post-processing handles specific RST constructs (:param, :type, :returns, :raises) but not others. Adding Google-style summary lines to docstrings (scikit-hep#3946) exposed this gap: summary lines were not indented inside the py:function directive, breaking the parameter rendering. sphinx-autoapi, which parses source via astroid without importing, is now available as a standard Sphinx extension. It lets Sphinx parse the generated RST natively, avoiding the need for regex-based post-processing. This commit replaces prepare_docstrings.py with sphinx-autoapi: - Add sphinx-autoapi and napoleon extensions - Monkey-patch output paths to preserve existing ak.* URL structure - Custom Jinja templates for display names and GitHub source links - Docstring filter for cross-references, backtick escaping, and member links - Skip internal submodules that collide on case-insensitive filesystems Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
TaiSakuma
added a commit
that referenced
this pull request
Apr 7, 2026
* docs: replace prepare_docstrings.py with sphinx-autoapi When prepare_docstrings.py was developed in 2020 (#187, #158), there was no standard Sphinx solution for generating API docs without importing the package. The script used ast to parse source files and called napoleon directly, then applied regex-based post-processing to indent RST directives. This post-processing handles specific RST constructs (:param, :type, :returns, :raises) but not others. Adding Google-style summary lines to docstrings (#3946) exposed this gap: summary lines were not indented inside the py:function directive, breaking the parameter rendering. sphinx-autoapi, which parses source via astroid without importing, is now available as a standard Sphinx extension. It lets Sphinx parse the generated RST natively, avoiding the need for regex-based post-processing. This commit replaces prepare_docstrings.py with sphinx-autoapi: - Add sphinx-autoapi and napoleon extensions - Monkey-patch output paths to preserve existing ak.* URL structure - Custom Jinja templates for display names and GitHub source links - Docstring filter for cross-references, backtick escaping, and member links - Skip internal submodules that collide on case-insensitive filesystems Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: suppress internal _module. pages from autoapi output Internal submodule pages (e.g., ak._module.recordarray) are generated to avoid case collisions on case-insensitive filesystems but should not produce visible HTML pages. Suppress them by checking for the _module. prefix in the module template. Reduces orphan pages from 208 to 106. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add blank line in ak.flatten docstring to trigger Tests workflow (#3948) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.