From a3a2e5a5ad7918df5ade66cd72e78c82de20f609 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 24 Sep 2022 12:34:38 -0500 Subject: [PATCH 1/2] feat!: Remove sphinx_toctree_autodoc_fix (Superseded by sphinx 5.2+) --- README.md | 18 ------ docs/index.md | 1 - docs/sphinx_toctree_autodoc_fix/index.md | 31 ---------- tests/test_sphinx_toctree_autodoc_fix.py | 79 ------------------------ 4 files changed, 129 deletions(-) delete mode 100644 docs/sphinx_toctree_autodoc_fix/index.md delete mode 100644 tests/test_sphinx_toctree_autodoc_fix.py diff --git a/README.md b/README.md index 9f9231c..1051e05 100644 --- a/README.md +++ b/README.md @@ -132,24 +132,6 @@ In your _conf.py_: See more: -### Table of contents for autodoc - -`sphinx.ext.autodoc` doesn't link objects in the table of contents. So we need a -plugin to help. - -See more: - -#### Configuration - -1. Add `'sphinx_toctree_autodoc_fix'` to `extensions` - - ```python - extensions = [ - # ... - "sphinx_toctree_autodoc_fix", - ] - ``` - ## Install ```console diff --git a/docs/index.md b/docs/index.md index d5fbad2..29006d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,6 @@ quickstart doctest/index -sphinx_toctree_autodoc_fix/index linkify_issues/index ``` diff --git a/docs/sphinx_toctree_autodoc_fix/index.md b/docs/sphinx_toctree_autodoc_fix/index.md deleted file mode 100644 index 3a48bdb..0000000 --- a/docs/sphinx_toctree_autodoc_fix/index.md +++ /dev/null @@ -1,31 +0,0 @@ -(sphinx_toctree_autodoc_fix)= -(sphinx-toctree-signature)= - -# ToC + `sphinx.ext.autodoc` fixer - -Table of Contents won't generate for `sphinx.ext.autodoc`, see -[sphinx#6316]. This has been an open issue since April 22nd, 2019. - -[sphinx#6316]: https://github.com/sphinx-doc/sphinx/issues/6316 - -## Configuration - -In your _conf.py_: - -1. Add `'sphinx_toctree_autodoc_fix'` to `extensions` - - ```python - extensions = [ - # ... - "sphinx_toctree_autodoc_fix", - ] - ``` - -## API - -```{eval-rst} -.. automodule:: sphinx_toctree_autodoc_fix - :members: - :show-inheritance: - :undoc-members: -``` diff --git a/tests/test_sphinx_toctree_autodoc_fix.py b/tests/test_sphinx_toctree_autodoc_fix.py deleted file mode 100644 index a3c1a5e..0000000 --- a/tests/test_sphinx_toctree_autodoc_fix.py +++ /dev/null @@ -1,79 +0,0 @@ -import pathlib -import textwrap -import typing as t - -import pytest - -from docutils import nodes -from sphinx import addnodes -from sphinx.testing.util import SphinxTestApp, assert_node - -if t.TYPE_CHECKING: - from .conftest import MakeAppParams - - -class ToCTreeTestFixture(t.NamedTuple): - test_id: str - text: str - - -FIXTURES = [ - ToCTreeTestFixture( - test_id="basic", - text=textwrap.dedent( - """ -.. autoclass:: doctest_docutils.DocutilsDocTestFinder - :members: - :show-inheritance: - :undoc-members: - -contents: - -.. contents:: - :local: - -toctree: - -.. toctree:: - :local: -""" - ), - ), -] - - -@pytest.mark.parametrize( - ToCTreeTestFixture._fields, FIXTURES, ids=[f.test_id for f in FIXTURES] -) -def test_toc_shows_api_docs( - make_app: t.Callable[[t.Any], SphinxTestApp], - make_app_params: "MakeAppParams", - test_id: str, - text: str, -) -> None: - """Assert sphinx_toctree_autodoc_fix collects entries from autodoc. - - Normal sphinx ToC does not collect them< see sphinx-doc#6316 - """ - args, kwargs = make_app_params( - index=text, - confoverrides={ - "extensions": ["sphinx_toctree_autodoc_fix", "sphinx.ext.autodoc"], - "html_theme": "basic", - }, - ) - app = make_app(*args, **kwargs) - app.build() - - content = (pathlib.Path(app.outdir) / "index.html").read_text(encoding="utf8") - - assert "DocutilsDocTestFinder" in content - assert "Table of Contents" in content - assert 'href="#doctest_docutils.DocutilsDocTestFinder' in content - - toctree = app.env.tocs["index"] - assert "DocutilsDocTestFinder" == toctree[0][0].astext() - assert_node( - toctree[1][0], - [nodes.list_item, addnodes.compact_paragraph], - ) From 63513d7ee6a7703993c403bbb8571e2d6ba0086e Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 24 Sep 2022 13:06:09 -0500 Subject: [PATCH 2/2] docs(CHANGES): Note removal of sphinx_toctree_autodoc_fix --- CHANGES | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CHANGES b/CHANGES index 26acb2d..ca0be3b 100644 --- a/CHANGES +++ b/CHANGES @@ -24,6 +24,26 @@ $ pip install --user --upgrade --pre gp-libs - doctest_docutils: :mod:`doctest` w/ docutils support (and markdown) +### Removed features + +- `sphinx_toctree_autodoc_fix` was removed in v0.0.1a12 + + Overcome by [Sphinx 5.2](https://pypi.org/project/Sphinx/5.2.0) bakes this in by default: + + Settings options: + + - `add_function_parentheses = False` (default: `True`) + - `toc_object_entries_show_parents` can be (default: `'domain'`): + - `toc_object_entries_show_parents = 'domain'` + - `toc_object_entries_show_parents = 'hide'` + - `toc_object_entries_show_parents = 'all'` + + See also: + + - https://github.com/sphinx-doc/sphinx/issues/6316 + - https://github.com/sphinx-doc/sphinx/pull/10807 + - https://gist.github.com/agoose77/e8f0f8f7d7133e73483ca5c2dd7b907f + ### Documentation - Initial docs, packaging, etc.