Skip to content

Commit dd2e4e8

Browse files
TDKornTDKorn
committed
Update documentation
1 parent 749f34b commit dd2e4e8

File tree

7 files changed

+88
-63
lines changed

7 files changed

+88
-63
lines changed

‎.readthedocs.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Build PDF & ePub
9+
formats: all
10+
11+
# Set the version of Python and other tools you might need
12+
build:
13+
os: ubuntu-20.04
14+
tools:
15+
python: "3.10"
16+
17+
# Build documentation in the docs/ directory with Sphinx
18+
sphinx:
19+
configuration: docs/source/conf.py
20+
21+
# Optionally declare the Python requirements required to build your docs
22+
python:
23+
install:
24+
- method: pip
25+
path: .
26+
- requirements: docs/requirements.txt
27+
- requirements: requirements.txt

‎README.rst

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -146,17 +146,6 @@ Optional Configuration Variables
146146

147147
Add any of the following configuration variables to your ``conf.py``
148148

149-
``top_level``
150-
^^^^^^^^^^^^^^^^^^^
151-
152-
.. code-block:: python
153-
154-
top_level: str
155-
156-
157-
The name of the top-level package. For this repo, it would be ``sphinx_github_style``
158-
159-
...
160149

161150
``linkcode_blob``
162151
^^^^^^^^^^^^^^^^^^^
@@ -169,7 +158,7 @@ The name of the top-level package. For this repo, it would be ``sphinx_github_st
169158
The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"``
170159

171160
* ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead
172-
* ``last_tag``: links to the most recently tagged commit; if no tags exist, uses ``head``
161+
* ``last_tag``: links to the most recent commit tag on the currently checked out branch
173162
* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"``
174163

175164

@@ -205,7 +194,7 @@ The text to use for the linkcode link
205194

206195
.. code-block:: python
207196
208-
linkcode_resolve: types.FunctionType
197+
linkcode_resolve: Callable
209198
210199
A ``linkcode_resolve()`` function to use for resolving the link target
211200

‎README_PyPi.rst

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -132,17 +132,6 @@ Optional Configuration Variables
132132

133133
Add any of the following configuration variables to your ``conf.py``
134134

135-
``top_level``
136-
^^^^^^^^^^^^^^^^^^^
137-
138-
.. code-block:: python
139-
140-
top_level: str
141-
142-
143-
The name of the top-level package. For this repo, it would be ``sphinx_github_style``
144-
145-
...
146135

147136
``linkcode_blob``
148137
^^^^^^^^^^^^^^^^^^^
@@ -155,7 +144,7 @@ The name of the top-level package. For this repo, it would be ``sphinx_github_st
155144
The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"``
156145

157146
* ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead
158-
* ``last_tag``: links to the most recently tagged commit; if no tags exist, uses ``head``
147+
* ``last_tag``: links to the most recent commit tag on the currently checked out branch
159148
* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"``
160149

161150

@@ -191,7 +180,7 @@ The text to use for the linkcode link
191180

192181
.. code-block:: python
193182
194-
linkcode_resolve: types.FunctionType
183+
linkcode_resolve: Callable
195184
196185
A ``linkcode_resolve()`` function to use for resolving the link target
197186

‎docs/source/README.rst

Lines changed: 20 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -118,70 +118,56 @@ Optional Configuration Variables
118118

119119
Add any of the following configuration variables to your ``conf.py``
120120

121-
``top_level``
122-
^^^^^^^^^^^^^^^^^^^
123-
124-
.. code-block:: python
125-
126-
top_level: str
127-
128-
129-
The name of the top-level package. For this repo, it would be ``sphinx_github_style``
130-
131-
...
132121

133122
``linkcode_blob``
134123
^^^^^^^^^^^^^^^^^^^
135124

136-
.. code-block:: python
137-
138-
linkcode_blob: str = "head"
139-
125+
.. confval:: linkcode_blob
140126

141-
The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"``
127+
The blob to link to on GitHub - any of ``"head"``, ``"last_tag"``, or ``"{blob}"``
142128

143-
* ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead
144-
* ``last_tag``: links to the most recently tagged commit; if no tags exist, uses ``head``
145-
* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"``
129+
* ``head`` (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead
130+
* ``last_tag``: links to the most recent commit tag on the currently checked out branch
131+
* ``blob``: links to any blob you want, for example ``"master"`` or ``"v2.0.1"``
146132

133+
:type: **str**
134+
:default: ``"head"``
147135

148-
...
149136

150137
``linkcode_url``
151138
^^^^^^^^^^^^^^^^^^^
152139

153-
.. code-block:: python
140+
.. confval:: linkcode_url
154141

155-
linkcode_url: str = f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"
142+
The link to your GitHub repository formatted as ``https://github.com/user/repo``
156143

157-
The link to your GitHub repository formatted as ``https://github.com/user/repo``
144+
* If not provided, will attempt to create the link from the :external+sphinx:confval:`html_context` dict
158145

159-
* If not provided, will attempt to create the link from the ``html_context`` dict
146+
:type: **str**
147+
:default: ``f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"``
160148

161-
...
162149

163150
``linkcode_link_text``
164151
^^^^^^^^^^^^^^^^^^^^^^
165152

166-
.. code-block:: python
167-
168-
linkcode_link_text: str = "View on GitHub"
153+
.. confval:: linkcode_link_text
169154

155+
The text to use for the linkcode link
170156

171-
The text to use for the linkcode link
157+
:type: **str**
158+
:default: ``"View on GitHub"``
172159

173-
...
174160

175161
``linkcode_resolve``
176162
^^^^^^^^^^^^^^^^^^^^^^^^
177163

178-
.. code-block:: python
164+
.. confval:: linkcode_resolve
179165

180-
linkcode_resolve: types.FunctionType
166+
A ``linkcode_resolve()`` function to use when resolving the link target with :mod:`sphinx.ext.linkcode`
181167

182-
A ``linkcode_resolve()`` function to use for resolving the link target
168+
:type: **Callable**
169+
:default: Return value from :func:`~.get_linkcode_resolve`
183170

184-
* Uses default function from :func:`~.get_linkcode_resolve` if not specified (recommended)
185171

186172
|
187173

‎docs/source/_static/custom.css

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,9 @@ code.literal {
2020
.rst-content .viewcode-back, .rst-content .viewcode-link {
2121
color: #00e;
2222
padding-left: 12px;
23-
}
23+
}
24+
/*Hide headers for config values; allows confval directives to be accessible via TOC*/
25+
#optional-configuration-variables h3 {
26+
visibility: hidden;
27+
display: none !important;
28+
}

‎docs/source/conf.py

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,9 @@
102102
'github_repo': repo,
103103
}
104104

105+
if 'html' not in sys.argv:
106+
pygments_style = 'sphinx'
107+
105108
if not on_rtd:
106109
site_url = "https://tdkorn.github.io/sphinx-github-style/"
107110

@@ -128,6 +131,7 @@
128131
intersphinx_mapping = {
129132
'python': ('https://docs.python.org/3', None),
130133
'requests': ('https://requests.readthedocs.io/en/latest/', None),
134+
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
131135
}
132136

133137
# ~~~~ AutoSectionLabel ~~~~
@@ -182,5 +186,30 @@ def skip(app, what, name, obj, would_skip, options):
182186

183187

184188
def setup(app):
189+
from sphinx.domains.python import PyField
190+
from sphinx.util.docfields import Field
191+
from sphinx.locale import _
192+
185193
app.connect('autodoc-skip-member', skip)
186194
app.add_css_file("custom.css")
195+
app.add_object_type(
196+
'confval',
197+
'confval',
198+
objname='configuration value',
199+
indextemplate='pair: %s; configuration value',
200+
doc_field_types=[
201+
PyField(
202+
'type',
203+
label=_('Type'),
204+
has_arg=False,
205+
names=('type',),
206+
bodyrolename='class'
207+
),
208+
Field(
209+
'default',
210+
label=_('Default'),
211+
has_arg=False,
212+
names=('default',),
213+
),
214+
]
215+
)

‎sphinx_github_style/add_linkcode_class.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77

88

99
def add_linkcode_node_class(app: Sphinx, doctree: Node, docname: str) -> None:
10-
"""Changes every :class:`~.Node` added by linkcode to use the ``"linkcode-link"`` class
10+
"""Changes every :class:`~.Node` added by :mod:`sphinx.ext.linkcode` to use the ``"linkcode-link"`` class
1111
12-
This creates separation from the nodes added by ``sphinx.ext.viewcode``, allowing
12+
This creates separation from the nodes added by :mod:`sphinx.ext.viewcode`, allowing
1313
for different link text and CSS styling
1414
1515
Sets the link text to ``linkcode_link_text``, or ``"View on GitHub"`` if not provided

0 commit comments

Comments
 (0)