Skip to content

Commit f473300

Browse files
mdboomAA-Turner
mdboom
and
AA-Turner
authored
Fix #359: Add a Sphinx benchmark (#360)
* Add a Sphinx benchmark * Fix tests * Fix tests and address comments in the PR * Remove unused check-warnings.py * Removed unused extensions (lexers, c_annotations, audit_events, glossary_search) * Remove patchlevel * Remove custom JS scripts * Removed unused extensions (lexers, c_annotations, audit_events, glossary_search) * Remove all HTML templates (we are using the dummy builder) * Remove sphinxext.opengraph config (not installed in the benchmark) * Minimise `conf.py` - Remove config for builders we don't use (doctest, gettext, html, latex, epub, coverage, linkcheck) - Remove config for nitpicky mode (not enabled in the benchmark) - Remove irrelevant setup (e.g. doctest) - Remove setup for `notfound.extension` - Remove non-determinism with usage of `time.strftime()` * Minimise pyspecific * Use Sphinx 7.3.7 * Update pyperformance/data-files/benchmarks/bm_sphinx/run_benchmark.py Co-authored-by: Adam Turner <[email protected]> --------- Co-authored-by: Adam Turner <[email protected]>
1 parent 22b2819 commit f473300

27 files changed

+11568
-0
lines changed

‎pyperformance/data-files/benchmarks/MANIFEST

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ richards <local>
7575
richards_super <local>
7676
scimark <local>
7777
spectral_norm <local>
78+
sphinx <local>
7879
sqlalchemy_declarative <local>
7980
sqlalchemy_imperative <local>
8081
sqlglot <local>

‎pyperformance/data-files/benchmarks/bm_sphinx/data/Doc/about.rst

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
=====================
2+
About these documents
3+
=====================
4+
5+
6+
These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
7+
document processor specifically written for the Python documentation.
8+
9+
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
10+
.. _Sphinx: https://www.sphinx-doc.org/
11+
12+
.. In the online version of these documents, you can submit comments and suggest
13+
changes directly on the documentation pages.
14+
15+
Development of the documentation and its toolchain is an entirely volunteer
16+
effort, just like Python itself. If you want to contribute, please take a
17+
look at the :ref:`reporting-bugs` page for information on how to do so. New
18+
volunteers are always welcome!
19+
20+
Many thanks go to:
21+
22+
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
23+
and writer of much of the content;
24+
* the `Docutils <https://docutils.sourceforge.io/>`_ project for creating
25+
reStructuredText and the Docutils suite;
26+
* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
27+
got many good ideas.
28+
29+
30+
Contributors to the Python Documentation
31+
----------------------------------------
32+
33+
Many people have contributed to the Python language, the Python standard
34+
library, and the Python documentation. See :source:`Misc/ACKS` in the Python
35+
source distribution for a partial list of contributors.
36+
37+
It is only with the input and contributions of the Python community
38+
that Python has such wonderful documentation -- Thank You!

‎pyperformance/data-files/benchmarks/bm_sphinx/data/Doc/bugs.rst

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
.. _reporting-bugs:
2+
3+
*****************
4+
Dealing with Bugs
5+
*****************
6+
7+
Python is a mature programming language which has established a reputation for
8+
stability. In order to maintain this reputation, the developers would like to
9+
know of any deficiencies you find in Python.
10+
11+
It can be sometimes faster to fix bugs yourself and contribute patches to
12+
Python as it streamlines the process and involves less people. Learn how to
13+
:ref:`contribute <contributing-to-python>`.
14+
15+
Documentation bugs
16+
==================
17+
18+
If you find a bug in this documentation or would like to propose an improvement,
19+
please submit a bug report on the :ref:`tracker <using-the-tracker>`. If you
20+
have a suggestion on how to fix it, include that as well.
21+
22+
You can also open a discussion item on our
23+
`Documentation Discourse forum <https://discuss.python.org/c/documentation/26>`_.
24+
25+
If you find a bug in the theme (HTML / CSS / JavaScript) of the
26+
documentation, please submit a bug report on the `python-doc-theme bug
27+
tracker <https://github.com/python/python-docs-theme>`_.
28+
29+
If you're short on time, you can also email documentation bug reports to
30+
[email protected] (behavioral bugs can be sent to [email protected]).
31+
'docs@' is a mailing list run by volunteers; your request will be noticed,
32+
though it may take a while to be processed.
33+
34+
.. seealso::
35+
36+
`Documentation bugs`_
37+
A list of documentation bugs that have been submitted to the Python issue tracker.
38+
39+
`Issue Tracking <https://devguide.python.org/tracker/>`_
40+
Overview of the process involved in reporting an improvement on the tracker.
41+
42+
`Helping with Documentation <https://devguide.python.org/docquality/#helping-with-documentation>`_
43+
Comprehensive guide for individuals that are interested in contributing to Python documentation.
44+
45+
`Documentation Translations <https://devguide.python.org/documentation/translating/>`_
46+
A list of GitHub pages for documentation translation and their primary contacts.
47+
48+
49+
.. _using-the-tracker:
50+
51+
Using the Python issue tracker
52+
==============================
53+
54+
Issue reports for Python itself should be submitted via the GitHub issues
55+
tracker (https://github.com/python/cpython/issues).
56+
The GitHub issues tracker offers a web form which allows pertinent information
57+
to be entered and submitted to the developers.
58+
59+
The first step in filing a report is to determine whether the problem has
60+
already been reported. The advantage in doing so, aside from saving the
61+
developers' time, is that you learn what has been done to fix it; it may be that
62+
the problem has already been fixed for the next release, or additional
63+
information is needed (in which case you are welcome to provide it if you can!).
64+
To do this, search the tracker using the search box at the top of the page.
65+
66+
If the problem you're reporting is not already in the list, log in to GitHub.
67+
If you don't already have a GitHub account, create a new account using the
68+
"Sign up" link.
69+
It is not possible to submit a bug report anonymously.
70+
71+
Being now logged in, you can submit an issue.
72+
Click on the "New issue" button in the top bar to report a new issue.
73+
74+
The submission form has two fields, "Title" and "Comment".
75+
76+
For the "Title" field, enter a *very* short description of the problem;
77+
fewer than ten words is good.
78+
79+
In the "Comment" field, describe the problem in detail, including what you
80+
expected to happen and what did happen. Be sure to include whether any
81+
extension modules were involved, and what hardware and software platform you
82+
were using (including version information as appropriate).
83+
84+
Each issue report will be reviewed by a developer who will determine what needs to
85+
be done to correct the problem. You will receive an update each time an action is
86+
taken on the issue.
87+
88+
89+
.. seealso::
90+
91+
`How to Report Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
92+
Article which goes into some detail about how to create a useful bug report.
93+
This describes what kind of information is useful and why it is useful.
94+
95+
`Bug Writing Guidelines <https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html>`_
96+
Information about writing a good bug report. Some of this is specific to the
97+
Mozilla project, but describes general good practices.
98+
99+
.. _contributing-to-python:
100+
101+
Getting started contributing to Python yourself
102+
===============================================
103+
104+
Beyond just reporting bugs that you find, you are also welcome to submit
105+
patches to fix them. You can find more information on how to get started
106+
patching Python in the `Python Developer's Guide`_. If you have questions,
107+
the `core-mentorship mailing list`_ is a friendly place to get answers to
108+
any and all questions pertaining to the process of fixing issues in Python.
109+
110+
.. _Documentation bugs: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs
111+
.. _Python Developer's Guide: https://devguide.python.org/
112+
.. _core-mentorship mailing list: https://mail.python.org/mailman3/lists/core-mentorship.python.org/

‎pyperformance/data-files/benchmarks/bm_sphinx/data/Doc/conf.py

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import os
2+
import sys
3+
4+
sys.path.append(os.path.abspath('tools/extensions'))
5+
6+
extensions = [
7+
'pyspecific',
8+
'sphinx.ext.extlinks',
9+
]
10+
11+
manpages_url = 'https://manpages.debian.org/{path}'
12+
13+
# General substitutions.
14+
project = 'Python'
15+
copyright = f"2001, Python Software Foundation"
16+
17+
version = release = sys.version.split(" ", 1)[0]
18+
19+
rst_epilog = f"""
20+
.. |python_version_literal| replace:: ``Python {version}``
21+
.. |python_x_dot_y_literal| replace:: ``python{version}``
22+
.. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}``
23+
"""
24+
25+
# There are two options for replacing |today|: either, you set today to some
26+
# non-false value, then it is used:
27+
today = ''
28+
# Else, today_fmt is used as the format for a strftime call.
29+
today_fmt = '%B %d, %Y'
30+
31+
# By default, highlight as Python 3.
32+
highlight_language = 'python3'
33+
34+
# Minimum version of sphinx required
35+
needs_sphinx = '6.2.1'
36+
37+
# Create table of contents entries for domain objects (e.g. functions, classes,
38+
# attributes, etc.). Default is True.
39+
toc_object_entries = False
40+
41+
# Disable Docutils smartquotes for several translations
42+
smartquotes_excludes = {
43+
'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'],
44+
'builders': ['man', 'text'],
45+
}
46+
47+
# Avoid a warning with Sphinx >= 4.0
48+
root_doc = 'contents'
49+
50+
extlinks = {
51+
"cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
52+
"cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
53+
"pypi": ("https://pypi.org/project/%s/", "%s"),
54+
"source": ('https://github.com/python/cpython/tree/3.13/%s', "%s"),
55+
}
56+
extlinks_detect_hardcoded_links = True

‎pyperformance/data-files/benchmarks/bm_sphinx/data/Doc/constraints.txt

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# We have upper bounds on our transitive dependencies here
2+
# To avoid new releases unexpectedly breaking our build.
3+
# This file can be updated on an ad-hoc basis,
4+
# though it will probably have to be updated
5+
# whenever Doc/requirements.txt is updated.
6+
7+
# Direct dependencies of Sphinx
8+
babel<3
9+
colorama<0.5
10+
imagesize<2
11+
Jinja2<4
12+
packaging<25
13+
Pygments<3
14+
requests<3
15+
snowballstemmer<3
16+
# keep lower-bounds until Sphinx 8.1 is released
17+
# https://github.com/sphinx-doc/sphinx/pull/12756
18+
sphinxcontrib-applehelp>=1.0.7,<3
19+
sphinxcontrib-devhelp>=1.0.6,<3
20+
sphinxcontrib-htmlhelp>=2.0.6,<3
21+
sphinxcontrib-jsmath>=1.0.1,<2
22+
sphinxcontrib-qthelp>=1.0.6,<3
23+
sphinxcontrib-serializinghtml>=1.1.9,<3
24+
25+
# Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
26+
MarkupSafe<3

‎pyperformance/data-files/benchmarks/bm_sphinx/data/Doc/contents.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2+
Python Documentation contents
3+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4+
5+
.. toctree::
6+
7+
whatsnew/index.rst
8+
tutorial/index.rst
9+
using/index.rst
10+
reference/index.rst
11+
library/index.rst
12+
extending/index.rst
13+
c-api/index.rst
14+
installing/index.rst
15+
howto/index.rst
16+
faq/index.rst
17+
deprecations/index.rst
18+
glossary.rst
19+
20+
about.rst
21+
bugs.rst
22+
copyright.rst
23+
license.rst

‎pyperformance/data-files/benchmarks/bm_sphinx/data/Doc/copyright.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
*********
2+
Copyright
3+
*********
4+
5+
Python and this documentation is:
6+
7+
Copyright © 2001-2024 Python Software Foundation. All rights reserved.
8+
9+
Copyright © 2000 BeOpen.com. All rights reserved.
10+
11+
Copyright © 1995-2000 Corporation for National Research Initiatives. All rights
12+
reserved.
13+
14+
Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
15+
16+
-------
17+
18+
See :ref:`history-and-license` for complete license and permissions information.
19+

0 commit comments

Comments
 (0)