Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 7d00884

Browse filesBrowse files
tomschrtomschr
committed
Improve API documentation
* Use sphinx-apidoc to build API documentation * Amend tox.ini and call sphinx-apidoc * Remove old autosummary; it turned out it was difficult to configure and returned warning messages which were hard to fix. * Add semver version in footer * Add semver.__about__ to API doc * Unorthodox solution with sed * Remove obsolete config variables in docs/config.py * Add docs/_api/semver.__about__.rst as a placeholder * Add changelog.d/304.doc.rst (An old attempt was to use autosummary from https://stackoverflow.com/a/62613202; however, that didn't work quite well.) Co-authored-by: Tom Schraitle <tomschr@users.noreply.github.com>
1 parent bb2cb90 commit 7d00884
Copy full SHA for 7d00884

File tree

Expand file treeCollapse file tree

18 files changed

+178
-23
lines changed
Filter options
Expand file treeCollapse file tree

18 files changed

+178
-23
lines changed

‎.gitignore

Copy file name to clipboardExpand all lines: .gitignore
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -259,7 +259,8 @@ fabric.properties
259259
# --------
260260

261261

262-
263262
# Patch/Diff Files
264263
*.patch
265264
*.diff
265+
docs/_api
266+
!docs/_api/semver.__about__.rst

‎changelog.d/304.doc.rst

Copy file name to clipboard
+5Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Several improvements in documentation:
2+
3+
* Reorganize API documentation.
4+
* Add migration chapter from semver2 to semver3.
5+
* Distinguish between changlog for version 2 and 3

‎docs/_api/semver.__about__.rst

Copy file name to clipboard
+5Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
semver.\_\_about\_\_ module
2+
===========================
3+
4+
.. automodule:: semver.__about__
5+
:members:

‎docs/_static/css/custom.css

Copy file name to clipboardExpand all lines: docs/_static/css/custom.css
+5Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ div.related.top nav {
2626
margin-top: 0.5em;
2727
}
2828

29+
.sphinxsidebarwrapper .caption {
30+
margin-top: 1em;
31+
margin-bottom: -0.75em;
32+
}
33+
2934
.section h1 {
3035
font-weight: 700;
3136
}

‎docs/_templates/layout.html

Copy file name to clipboardExpand all lines: docs/_templates/layout.html
+45Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,48 @@
22
Import the theme's layout.
33
#}
44
{% extends "!layout.html" %}
5+
6+
{%- block footer %}
7+
<div class="footer">
8+
<p>
9+
{% if show_copyright %}&copy;{{ copyright }}.{% endif %}
10+
{% if theme_show_powered_by|lower == 'true' %}
11+
{% if show_copyright %}|{% endif %}
12+
{% if show_copyright %}|{% endif %}
13+
Powered by <a href="http://sphinx-doc.org/">Sphinx {{ sphinx_version }}</a>
14+
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster {{ alabaster_version }}</a>
15+
{% endif %}
16+
{%- if show_source and has_source and sourcename %}
17+
{% if show_copyright or theme_show_powered_by %}|{% endif %}
18+
<a href="{{ pathto('_sources/' + sourcename, true)|e }}"
19+
rel="nofollow">{{ _('Page source') }}</a>
20+
{%- endif %}
21+
</p>
22+
<p>
23+
For <a href="https://github.com/{{ theme_github_user }}/{{ theme_github_repo }}"
24+
>semver {{ version }}</a>
25+
</p>
26+
</div>
27+
28+
{% if theme_github_banner|lower != 'false' %}
29+
<a href="https://github.com/{{ theme_github_user }}/{{ theme_github_repo }}" class="github">
30+
<img style="position: absolute; top: 0; right: 0; border: 0;" src="{{ pathto('_static/' ~ theme_github_banner, 1) if theme_github_banner|lower != 'true' else 'https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png' }}" alt="Fork me on GitHub" class="github"/>
31+
</a>
32+
{% endif %}
33+
{% if theme_analytics_id %}
34+
<script type="text/javascript">
35+
36+
var _gaq = _gaq || [];
37+
_gaq.push(['_setAccount', '{{ theme_analytics_id }}']);
38+
_gaq.push(['_setDomainName', 'none']);
39+
_gaq.push(['_setAllowLinker', true]);
40+
_gaq.push(['_trackPageview']);
41+
42+
(function() {
43+
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
44+
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
45+
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
46+
})();
47+
</script>
48+
{% endif %}
49+
{%- endblock %}

‎docs/api.rst

Copy file name to clipboard
+6-4Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
.. _api:
22

3+
###
34
API
4-
===
5+
###
56

6-
.. automodule:: semver
7-
:members:
8-
:undoc-members:
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
_api/semver

‎docs/coerce.py

Copy file name to clipboardExpand all lines: docs/coerce.py
+5-3Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import re
2-
import semver
2+
from semver import Version
3+
from typing import Optional, Tuple
4+
35

46
BASEVERSION = re.compile(
57
r"""[vV]?
@@ -15,7 +17,7 @@
1517
)
1618

1719

18-
def coerce(version):
20+
def coerce(version: str) -> Tuple[Version, Optional[str]]:
1921
"""
2022
Convert an incomplete version string into a semver-compatible Version
2123
object
@@ -37,6 +39,6 @@ def coerce(version):
3739
ver = {
3840
key: 0 if value is None else value for key, value in match.groupdict().items()
3941
}
40-
ver = semver.Version(**ver)
42+
ver = Version(**ver)
4143
rest = match.string[match.end() :] # noqa:E203
4244
return ver, rest

‎docs/conf.py

Copy file name to clipboardExpand all lines: docs/conf.py
+32-5Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,35 @@
1616
# add these directories to sys.path here. If the directory is relative to the
1717
# documentation root, use os.path.abspath to make it absolute, like shown here.
1818
#
19+
import codecs
1920
import os
21+
import re
2022
import sys
2123

2224
sys.path.insert(0, os.path.abspath("../src/"))
25+
# from semver import __version__ # noqa: E402
2326

24-
from semver import __version__ # noqa: E402
27+
28+
def read(*parts):
29+
"""
30+
Build an absolute path from *parts* and and return the contents of the
31+
resulting file. Assume UTF-8 encoding.
32+
"""
33+
here = os.path.abspath(os.path.dirname(__file__))
34+
with codecs.open(os.path.join(here, *parts), "rb", "utf-8") as f:
35+
return f.read()
36+
37+
38+
def find_version(*file_paths):
39+
"""
40+
Build a path from *file_paths* and search for a ``__version__``
41+
string inside.
42+
"""
43+
version_file = read(*file_paths)
44+
version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", version_file, re.M)
45+
if version_match:
46+
return version_match.group(1)
47+
raise RuntimeError("Unable to find version string.")
2548

2649

2750
# -- General configuration ------------------------------------------------
@@ -35,12 +58,16 @@
3558
# ones.
3659
extensions = [
3760
"sphinx.ext.autodoc",
61+
"sphinx.ext.autosummary",
3862
"sphinx_autodoc_typehints",
3963
"sphinx.ext.intersphinx",
40-
"sphinx.ext.napoleon",
4164
"sphinx.ext.extlinks",
4265
]
4366

67+
autoclass_content = "class"
68+
autodoc_default_options = {}
69+
70+
4471
# Add any paths that contain templates here, relative to this directory.
4572
templates_path = ["_templates"]
4673

@@ -62,16 +89,16 @@
6289
# built documents.
6390
#
6491
# The short X.Y version.
65-
version = __version__
92+
release = find_version("../src/semver/__about__.py")
6693
# The full version, including alpha/beta/rc tags.
67-
release = version
94+
version = release # .rsplit(u".", 1)[0]
6895

6996
# The language for content autogenerated by Sphinx. Refer to documentation
7097
# for a list of supported languages.
7198
#
7299
# This is also used if you do content translation via gettext catalogs.
73100
# Usually you set "language" from the command line for these cases.
74-
language = None
101+
language = "en"
75102

76103
# List of patterns, relative to source directory, that match files and
77104
# directories to ignore when looking for source files.

‎docs/readme.rst

Copy file name to clipboard
+3-1Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
.. include:: ../README.rst
1+
If you are searching for how to stay compatible
2+
with semver3, refer to :ref:`semver2-to-3`.
23

4+
.. include:: ../README.rst

‎docs/usage.rst

Copy file name to clipboardExpand all lines: docs/usage.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ A :class:`semver.Version` instance can be created in different ways:
8989
ValueError: 'major' is negative. A version can only be positive.
9090

9191
As a minimum requirement, your dictionary needs at least the
92-
be positive.
92+
be positive.
9393

9494
>>> semver.Version(-1)
9595
Traceback (most recent call last):

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.