Skip to content

Commit dd08897

Browse files
domdfcodingdomdfcoding
committed
Improve docs layout.
1 parent 74c87e8 commit dd08897

7 files changed

Lines changed: 154 additions & 4 deletions

File tree

‎doc-source/api.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,4 @@ API Reference
33
================
44

55
.. automodule:: flake8_strftime
6-
:private-members:
7-
:special-members:
86
:undoc-members:

‎doc-source/autosummary_widths.py‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Based on https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/ext/autosummary/__init__.py
2+
#
3+
# Copyright (c) 2007-2021 by the Sphinx team.
4+
# All rights reserved.
5+
#
6+
# Redistribution and use in source and binary forms, with or without
7+
# modification, are permitted provided that the following conditions are
8+
# met:
9+
#
10+
# * Redistributions of source code must retain the above copyright
11+
# notice, this list of conditions and the following disclaimer.
12+
#
13+
# * Redistributions in binary form must reproduce the above copyright
14+
# notice, this list of conditions and the following disclaimer in the
15+
# documentation and/or other materials provided with the distribution.
16+
#
17+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18+
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19+
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20+
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21+
# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22+
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23+
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24+
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25+
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26+
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27+
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28+
#
29+
30+
# stdlib
31+
from itertools import chain
32+
from typing import List, Tuple
33+
34+
# 3rd party
35+
from docutils import nodes
36+
from docutils.statemachine import StringList
37+
from domdf_python_tools import stringlist
38+
from sphinx import addnodes
39+
from sphinx.application import Sphinx
40+
from sphinx.config import Config
41+
from sphinx.ext.autosummary import Autosummary, autosummary_table
42+
from sphinx.util import rst
43+
from sphinx.util.docutils import SphinxDirective, switch_source_input
44+
from sphinx_toolbox import latex
45+
46+
47+
class AutosummaryWidths(Autosummary):
48+
49+
def get_table(self, items: List[Tuple[str, str, str, str]]) -> List[nodes.Node]:
50+
"""
51+
Generate a proper list of table nodes for autosummary:: directive.
52+
53+
:param items: A a list produced by :meth:`~.get_items`.
54+
"""
55+
table_spec = addnodes.tabular_col_spec()
56+
# table_spec['spec'] = r'\Xx{1}{3}\Xx{2}{3}'
57+
# table_spec['spec'] = r'\Xx{3}{8}\Xx{5}{8}'
58+
# table_spec['spec'] = r'\Xx{7}{16}\Xx{9}{16}'
59+
60+
widths = chain.from_iterable(getattr(self.state.document, "autosummary_widths", ((1, 2), (1, 2))))
61+
table_spec["spec"] = r'\Xx{{{}}}{{{}}}\Xx{{{}}}{{{}}}'.format(*widths)
62+
63+
table = autosummary_table('')
64+
real_table = nodes.table('', classes=["longtable"])
65+
table.append(real_table)
66+
group = nodes.tgroup('', cols=2)
67+
real_table.append(group)
68+
group.append(nodes.colspec('', colwidth=10))
69+
group.append(nodes.colspec('', colwidth=90))
70+
body = nodes.tbody('')
71+
group.append(body)
72+
73+
def append_row(*column_texts: str) -> None:
74+
row = nodes.row('')
75+
source, line = self.state_machine.get_source_and_line()
76+
for text in column_texts:
77+
node = nodes.paragraph('')
78+
vl = StringList()
79+
vl.append(text, "%s:%d:<autosummary>" % (source, line))
80+
with switch_source_input(self.state, vl):
81+
self.state.nested_parse(vl, 0, node)
82+
try:
83+
if isinstance(node[0], nodes.paragraph):
84+
node = node[0]
85+
except IndexError:
86+
pass
87+
row.append(nodes.entry('', node))
88+
body.append(row)
89+
90+
for name, sig, summary, real_name in items:
91+
qualifier = "obj"
92+
if "nosignatures" not in self.options:
93+
col1 = ":{}:`{} <{}>`\\ {}".format(qualifier, name, real_name, rst.escape(sig).replace('(', "(​"))
94+
else:
95+
col1 = f":{qualifier}:`{name} <{real_name}>`"
96+
col2 = summary
97+
append_row(col1, col2)
98+
99+
return [table_spec, table]
100+
101+
102+
class WidthsDirective(SphinxDirective):
103+
required_arguments = 2
104+
105+
def run(self):
106+
widths = [arg.split('/') for arg in self.arguments]
107+
self.state.document.autosummary_widths = widths
108+
return []
109+
110+
111+
def configure(app: Sphinx, config: Config):
112+
"""
113+
114+
:param app:
115+
:param config:
116+
"""
117+
118+
latex_elements = getattr(app.config, "latex_elements", {}) # type: ignore
119+
120+
latex_preamble = stringlist.StringList(latex_elements.get("preamble", ''))
121+
latex_preamble.blankline()
122+
latex_preamble.append(r"\makeatletter")
123+
latex_preamble.append(r"\newcolumntype{\Xx}[2]{>{\raggedright\arraybackslash}p{\dimexpr")
124+
latex_preamble.append(r" (\linewidth-\arrayrulewidth)*#1/#2-\tw@\tabcolsep-\arrayrulewidth\relax}}")
125+
latex_preamble.append(r"\makeatother")
126+
latex_preamble.blankline()
127+
128+
latex_elements["preamble"] = str(latex_preamble)
129+
app.config.latex_elements = latex_elements # type: ignore
130+
131+
132+
def setup(app: Sphinx):
133+
app.add_directive("autosummary", AutosummaryWidths, override=True)
134+
app.add_directive("autosummary-widths", WidthsDirective)
135+
app.connect("build-finished", latex.replace_unknown_unicode)
136+
app.connect("config-inited", configure)

‎doc-source/index.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,10 @@ Installation
138138

139139
.. end installation
140140
141+
Contents
142+
---------
143+
144+
.. html-section::
141145

142146
.. toctree::
143147
:hidden:
@@ -146,7 +150,6 @@ Installation
146150

147151
.. toctree::
148152
:maxdepth: 3
149-
:caption: Documentation
150153

151154
usage
152155
api

‎doc-source/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
git+https://github.com/sphinx-toolbox/html-section
12
autodocsumm>=0.2.0
23
default-values>=0.4.2
34
extras-require>=0.2.0

‎flake8_strftime/__init__.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
# __init__.py
44
"""
55
A Flake8 plugin which checks for use of platform specific strftime codes.
6+
7+
.. autosummary-widths:: 1/3 2/3
68
"""
79
#
810
# Copyright (c) 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
@@ -53,7 +55,13 @@
5355
_win_re = re.compile(r"%#[dmHIMSj]")
5456

5557

56-
class Visitor(flake8_helper.Visitor): # noqa: D101
58+
class Visitor(flake8_helper.Visitor):
59+
"""
60+
AST node visitor for identifying platform specific strftime codes.
61+
62+
.. autoclasssumm::
63+
:autosummary-sections: ;;
64+
"""
5765

5866
def __init__(self) -> None:
5967
super().__init__()

‎pyproject.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@ extensions = [
7171
"seed_intersphinx_mapping",
7272
"sphinx_toolbox.pre_commit",
7373
"sphinx_toolbox.flake8",
74+
"html_section",
75+
"autosummary_widths",
7476
]
7577
sphinxemoji_style = "twemoji"
7678
gitstamp_fmt = "%d %b %Y"

‎repo_helper.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ classifiers:
3838
extra_sphinx_extensions:
3939
- sphinx_toolbox.pre_commit
4040
- sphinx_toolbox.flake8
41+
- html_section
42+
- autosummary_widths
4143

4244
entry_points:
4345
flake8.extension:

0 commit comments

Comments
 (0)