tjh.dev
1{
2 lib,
3 buildPythonPackage,
4 pythonAtLeast,
5 pythonOlder,
6 fetchFromGitHub,
7 fetchpatch2,
8 isPyPy,
9
10 # build-system
11 flit-core,
12
13 # dependencies
14 babel,
15 alabaster,
16 docutils,
17 imagesize,
18 importlib-metadata,
19 jinja2,
20 packaging,
21 pygments,
22 requests,
23 snowballstemmer,
24 sphinxcontrib-applehelp,
25 sphinxcontrib-devhelp,
26 sphinxcontrib-htmlhelp,
27 sphinxcontrib-jsmath,
28 sphinxcontrib-qthelp,
29 sphinxcontrib-serializinghtml,
30 sphinxcontrib-websupport,
31 tomli,
32
33 # check phase
34 defusedxml,
35 filelock,
36 html5lib,
37 pytestCheckHook,
38 pytest-xdist,
39}:
40
41buildPythonPackage rec {
42 pname = "sphinx";
43 version = "7.3.7";
44 format = "pyproject";
45 disabled = pythonOlder "3.9";
46
47 src = fetchFromGitHub {
48 owner = "sphinx-doc";
49 repo = "sphinx";
50 rev = "refs/tags/v${version}";
51 postFetch = ''
52 # Change ä to æ in file names, since ä can be encoded multiple ways on different
53 # filesystems, leading to different hashes on different platforms.
54 cd "$out";
55 mv tests/roots/test-images/{testimäge,testimæge}.png
56 sed -i 's/testimäge/testimæge/g' tests/{test_build*.py,roots/test-images/index.rst}
57 '';
58 hash = "sha256-XGGRWEvd1SbQsK8W5yxDzBd5hlvXcDzr8t5Qa6skH/M=";
59 };
60
61 patches = [
62 (fetchpatch2 {
63 name = "python-3.13-compat.patch";
64 url = "https://github.com/sphinx-doc/sphinx/commit/3496de62b743942115acb486cf35dfcc102586c3.patch";
65 hash = "sha256-5VBPOQeGyj3a8VBq4hc9S/eKaeVZeGCTNislwgsauZo=";
66 })
67 ];
68
69 build-system = [ flit-core ];
70
71 dependencies =
72 [
73 alabaster
74 babel
75 docutils
76 imagesize
77 jinja2
78 packaging
79 pygments
80 requests
81 snowballstemmer
82 sphinxcontrib-applehelp
83 sphinxcontrib-devhelp
84 sphinxcontrib-htmlhelp
85 sphinxcontrib-jsmath
86 sphinxcontrib-qthelp
87 sphinxcontrib-serializinghtml
88 # extra[docs]
89 sphinxcontrib-websupport
90 ]
91 ++ lib.optionals (pythonOlder "3.11") [ tomli ]
92 ++ lib.optionals (pythonOlder "3.10") [ importlib-metadata ];
93
94 __darwinAllowLocalNetworking = true;
95
96 nativeCheckInputs = [
97 defusedxml
98 filelock
99 html5lib
100 pytestCheckHook
101 pytest-xdist
102 ];
103
104 preCheck = ''
105 export HOME=$TMPDIR
106 '';
107
108 disabledTests =
109 [
110 # requires network access
111 "test_latex_images"
112 # racy
113 "test_defaults"
114 "test_check_link_response_only"
115 "test_anchors_ignored_for_url"
116 "test_autodoc_default_options"
117 "test_too_many_requests_retry_after_int_delay"
118 # racy with pytest-xdist
119 "test_domain_cpp_build_semicolon"
120 "test_class_alias"
121 "test_class_alias_having_doccomment"
122 "test_class_alias_for_imported_object_having_doccomment"
123 "test_decorators"
124 # requires cython_0, but fails miserably on 3.11
125 "test_cython"
126 # Could not fetch remote image: http://localhost:7777/sphinx.png
127 "test_copy_images"
128 ]
129 ++ lib.optionals (pythonAtLeast "3.12") [
130 # https://github.com/sphinx-doc/sphinx/issues/12430
131 "test_autodoc_type_aliases"
132 ]
133 ++ lib.optionals isPyPy [
134 # PyPy has not __builtins__ which get asserted
135 # https://doc.pypy.org/en/latest/cpython_differences.html#miscellaneous
136 "test_autosummary_generate_content_for_module"
137 "test_autosummary_generate_content_for_module_skipped"
138 # internals are asserted which are sightly different in PyPy
139 "test_autodoc_inherited_members_None"
140 "test_automethod_for_builtin"
141 "test_builtin_function"
142 "test_isattributedescriptor"
143 "test_methoddescriptor"
144 "test_partialfunction"
145 ];
146
147 meta = {
148 description = "Python documentation generator";
149 longDescription = ''
150 Sphinx makes it easy to create intelligent and beautiful documentation.
151
152 Here are some of Sphinx’s major features:
153 - Output formats: HTML (including Windows HTML Help), LaTeX (for printable
154 PDF versions), ePub, Texinfo, manual pages, plain text
155 - Extensive cross-references: semantic markup and automatic links for
156 functions, classes, citations, glossary terms and similar pieces of
157 information
158 - Hierarchical structure: easy definition of a document tree, with
159 automatic links to siblings, parents and children
160 - Automatic indices: general index as well as a language-specific module
161 indices
162 - Code handling: automatic highlighting using the Pygments highlighter
163 - Extensions: automatic testing of code snippets, inclusion of docstrings
164 from Python modules (API docs) via built-in extensions, and much more
165 functionality via third-party extensions.
166 - Themes: modify the look and feel of outputs via creating themes, and
167 re-use many third-party themes.
168 - Contributed extensions: dozens of extensions contributed by users; most
169 of them installable from PyPI.
170
171 Sphinx uses the reStructuredText markup language by default, and can read
172 MyST markdown via third-party extensions. Both of these are powerful and
173 straightforward to use, and have functionality for complex documentation
174 and publishing workflows. They both build upon Docutils to parse and write
175 documents.
176 '';
177 homepage = "https://www.sphinx-doc.org";
178 changelog = "https://www.sphinx-doc.org/en/master/changes.html";
179 license = lib.licenses.bsd3;
180 maintainers = lib.teams.sphinx.members;
181 };
182}