Skip to content

Commit ca3de16

Browse files
domdfcodingdomdfcoding
committed
Try to break PDF documentation up into sections as per the toctree captions.
1 parent 4a23581 commit ca3de16

File tree

4 files changed

+160
-111
lines changed

4 files changed

+160
-111
lines changed

‎doc-source/conf.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
"""
2929

3030
author = "Dominic Davis-Foster"
31-
project = "domdf_python_tools"
31+
project = "domdf_python_tools".replace('_', '-')
3232
slug = re.sub(r'\W+', '-', project.lower())
3333
release = version = __version__
3434
copyright = "2019-2021 Dominic Davis-Foster" # pylint: disable=redefined-builtin
@@ -53,6 +53,7 @@
5353
"seed_intersphinx_mapping",
5454
"sphinx_autofixture",
5555
"sphinx_highlights",
56+
"latex_toctree_sections",
5657
]
5758

5859
sphinxemoji_style = "twemoji"

‎doc-source/index.rst

Lines changed: 113 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -11,116 +11,119 @@ domdf_python_tools
1111
1212
.. start shields
1313
14-
.. list-table::
15-
:stub-columns: 1
16-
:widths: 10 90
17-
18-
* - Docs
19-
- |docs| |docs_check|
20-
* - Tests
21-
- |actions_linux| |actions_windows| |actions_macos| |coveralls|
22-
* - PyPI
23-
- |pypi-version| |supported-versions| |supported-implementations| |wheel|
24-
* - Anaconda
25-
- |conda-version| |conda-platform|
26-
* - Activity
27-
- |commits-latest| |commits-since| |maintained| |pypi-downloads|
28-
* - QA
29-
- |codefactor| |actions_flake8| |actions_mypy| |pre_commit_ci|
30-
* - Other
31-
- |license| |language| |requires|
32-
33-
.. |docs| rtfd-shield::
34-
:project: domdf_python_tools
35-
:alt: Documentation Build Status
36-
37-
.. |docs_check| actions-shield::
38-
:workflow: Docs Check
39-
:alt: Docs Check Status
40-
41-
.. |actions_linux| actions-shield::
42-
:workflow: Linux
43-
:alt: Linux Test Status
44-
45-
.. |actions_windows| actions-shield::
46-
:workflow: Windows
47-
:alt: Windows Test Status
48-
49-
.. |actions_macos| actions-shield::
50-
:workflow: macOS
51-
:alt: macOS Test Status
52-
53-
.. |actions_flake8| actions-shield::
54-
:workflow: Flake8
55-
:alt: Flake8 Status
56-
57-
.. |actions_mypy| actions-shield::
58-
:workflow: mypy
59-
:alt: mypy status
60-
61-
.. |requires| requires-io-shield::
62-
:alt: Requirements Status
63-
64-
.. |coveralls| coveralls-shield::
65-
:alt: Coverage
66-
67-
.. |codefactor| codefactor-shield::
68-
:alt: CodeFactor Grade
69-
70-
.. |pypi-version| pypi-shield::
71-
:project: domdf_python_tools
72-
:version:
73-
:alt: PyPI - Package Version
74-
75-
.. |supported-versions| pypi-shield::
76-
:project: domdf_python_tools
77-
:py-versions:
78-
:alt: PyPI - Supported Python Versions
79-
80-
.. |supported-implementations| pypi-shield::
81-
:project: domdf_python_tools
82-
:implementations:
83-
:alt: PyPI - Supported Implementations
84-
85-
.. |wheel| pypi-shield::
86-
:project: domdf_python_tools
87-
:wheel:
88-
:alt: PyPI - Wheel
89-
90-
.. |conda-version| image:: https://img.shields.io/conda/v/domdfcoding/domdf_python_tools?logo=anaconda
91-
:target: https://anaconda.org/domdfcoding/domdf_python_tools
92-
:alt: Conda - Package Version
93-
94-
.. |conda-platform| image:: https://img.shields.io/conda/pn/domdfcoding/domdf_python_tools?label=conda%7Cplatform
95-
:target: https://anaconda.org/domdfcoding/domdf_python_tools
96-
:alt: Conda - Platform
97-
98-
.. |license| github-shield::
99-
:license:
100-
:alt: License
101-
102-
.. |language| github-shield::
103-
:top-language:
104-
:alt: GitHub top language
105-
106-
.. |commits-since| github-shield::
107-
:commits-since: v2.7.0
108-
:alt: GitHub commits since tagged version
109-
110-
.. |commits-latest| github-shield::
111-
:last-commit:
112-
:alt: GitHub last commit
113-
114-
.. |maintained| maintained-shield:: 2021
115-
:alt: Maintenance
116-
117-
.. |pypi-downloads| pypi-shield::
118-
:project: domdf_python_tools
119-
:downloads: month
120-
:alt: PyPI - Downloads
121-
122-
.. |pre_commit_ci| pre-commit-ci-shield::
123-
:alt: pre-commit.ci status
14+
.. only:: html
15+
16+
.. list-table::
17+
:stub-columns: 1
18+
:widths: 10 90
19+
20+
* - Docs
21+
- |docs| |docs_check|
22+
* - Tests
23+
- |actions_linux| |actions_windows| |actions_macos| |coveralls|
24+
* - PyPI
25+
- |pypi-version| |supported-versions| |supported-implementations| |wheel|
26+
* - Anaconda
27+
- |conda-version| |conda-platform|
28+
* - Activity
29+
- |commits-latest| |commits-since| |maintained| |pypi-downloads|
30+
* - QA
31+
- |codefactor| |actions_flake8| |actions_mypy| |pre_commit_ci|
32+
* - Other
33+
- |license| |language| |requires|
34+
35+
.. |docs| rtfd-shield::
36+
:project: domdf_python_tools
37+
:alt: Documentation Build Status
38+
39+
.. |docs_check| actions-shield::
40+
:workflow: Docs Check
41+
:alt: Docs Check Status
42+
43+
.. |actions_linux| actions-shield::
44+
:workflow: Linux
45+
:alt: Linux Test Status
46+
47+
.. |actions_windows| actions-shield::
48+
:workflow: Windows
49+
:alt: Windows Test Status
50+
51+
.. |actions_macos| actions-shield::
52+
:workflow: macOS
53+
:alt: macOS Test Status
54+
55+
.. |actions_flake8| actions-shield::
56+
:workflow: Flake8
57+
:alt: Flake8 Status
58+
59+
.. |actions_mypy| actions-shield::
60+
:workflow: mypy
61+
:alt: mypy status
62+
63+
.. |requires| requires-io-shield::
64+
:alt: Requirements Status
65+
66+
.. |coveralls| coveralls-shield::
67+
:alt: Coverage
68+
69+
.. |codefactor| codefactor-shield::
70+
:alt: CodeFactor Grade
71+
72+
.. |pypi-version| pypi-shield::
73+
:project: domdf_python_tools
74+
:version:
75+
:alt: PyPI - Package Version
76+
77+
.. |supported-versions| pypi-shield::
78+
:project: domdf_python_tools
79+
:py-versions:
80+
:alt: PyPI - Supported Python Versions
81+
82+
.. |supported-implementations| pypi-shield::
83+
:project: domdf_python_tools
84+
:implementations:
85+
:alt: PyPI - Supported Implementations
86+
87+
.. |wheel| pypi-shield::
88+
:project: domdf_python_tools
89+
:wheel:
90+
:alt: PyPI - Wheel
91+
92+
.. |conda-version| image:: https://img.shields.io/conda/v/domdfcoding/domdf_python_tools?logo=anaconda
93+
:target: https://anaconda.org/domdfcoding/domdf_python_tools
94+
:alt: Conda - Package Version
95+
96+
.. |conda-platform| image:: https://img.shields.io/conda/pn/domdfcoding/domdf_python_tools?label=conda%7Cplatform
97+
:target: https://anaconda.org/domdfcoding/domdf_python_tools
98+
:alt: Conda - Platform
99+
100+
.. |license| github-shield::
101+
:license:
102+
:alt: License
103+
104+
.. |language| github-shield::
105+
:top-language:
106+
:alt: GitHub top language
107+
108+
.. |commits-since| github-shield::
109+
:commits-since: v2.7.0
110+
:alt: GitHub commits since tagged version
111+
112+
.. |commits-latest| github-shield::
113+
:last-commit:
114+
:alt: GitHub last commit
115+
116+
.. |maintained| maintained-shield:: 2021
117+
:alt: Maintenance
118+
119+
.. |pypi-downloads| pypi-shield::
120+
:project: domdf_python_tools
121+
:downloads: month
122+
:alt: PyPI - Downloads
123+
124+
.. |pre_commit_ci| pre-commit-ci-shield::
125+
:alt: pre-commit.ci status
126+
124127

125128
.. end shields
126129

‎doc-source/latex_toctree_sections.py

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# stdlib
2+
from typing import Any, Dict, List
3+
4+
# 3rd party
5+
import sphinx.directives.other
6+
from docutils import nodes
7+
from sphinx.application import Sphinx
8+
9+
__all__ = ["TocTreePlusDirective", "setup"]
10+
11+
12+
class TocTreePlusDirective(sphinx.directives.other.TocTree):
13+
14+
def run(self) -> List[nodes.Node]:
15+
16+
output = []
17+
caption = self.options.get("caption")
18+
19+
if (
20+
caption is not None and self.env.app.builder.name.lower() == "latex"
21+
and self.env.docname == self.env.config.master_doc
22+
):
23+
24+
latex_part_node = nodes.raw(text=f"\\part{{{caption}}}", format="latex")
25+
output.append(latex_part_node)
26+
# self.state.nested_parse(StringList(), self.content_offset, latex_part_node)
27+
28+
output.extend(super().run())
29+
return output
30+
31+
32+
def setup(app: Sphinx) -> Dict[str, Any]:
33+
"""
34+
Setup Sphinx Extension.
35+
36+
:param app:
37+
"""
38+
39+
app.add_directive("toctree", TocTreePlusDirective, override=True)
40+
41+
return {
42+
"parallel_read_safe": True,
43+
"parallel_write_safe": True,
44+
}

‎repo_helper.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ mypy_deps:
6363
extra_sphinx_extensions:
6464
- sphinx_autofixture
6565
- sphinx_highlights
66+
- latex_toctree_sections
6667

6768
tox_unmanaged:
6869
- testenv

0 commit comments

Comments
 (0)