tjh.dev
nixpkgs mirror (for testing)
github.com/NixOS/nixpkgs
nix
1{
2 lib,
3 buildPythonPackage,
4 pythonAtLeast,
5 pythonOlder,
6 fetchFromGitHub,
7 isPyPy,
8
9 # build-system
10 flit-core,
11
12 # dependencies
13 babel,
14 alabaster,
15 docutils,
16 imagesize,
17 jinja2,
18 packaging,
19 pygments,
20 requests,
21 roman-numerals,
22 snowballstemmer,
23 sphinxcontrib-applehelp,
24 sphinxcontrib-devhelp,
25 sphinxcontrib-htmlhelp,
26 sphinxcontrib-jsmath,
27 sphinxcontrib-qthelp,
28 sphinxcontrib-serializinghtml,
29 sphinxcontrib-websupport,
30 tomli,
31
32 # check phase
33 defusedxml,
34 pytestCheckHook,
35 pytest-xdist,
36 typing-extensions,
37 writableTmpDirAsHomeHook,
38
39 # reverse dependencies to test
40 breathe,
41}:
42
43buildPythonPackage rec {
44 pname = "sphinx";
45 version = "9.1.0";
46 pyproject = true;
47
48 disabled = pythonOlder "3.12";
49
50 src = fetchFromGitHub {
51 owner = "sphinx-doc";
52 repo = "sphinx";
53 tag = "v${version}";
54 postFetch = ''
55 # Change ä to æ in file names, since ä can be encoded multiple ways on different
56 # filesystems, leading to different hashes on different platforms.
57 cd "$out";
58 mv tests/roots/test-images/{testimäge,testimæge}.png
59 sed -i 's/testimäge/testimæge/g' tests/{test_build*.py,roots/test-images/index.rst}
60 '';
61 hash = "sha256-PgqjCeyHOhWtZjyzSZyvsPT0Q7yRyNDiW3x1fQq0K+8=";
62 };
63
64 build-system = [ flit-core ];
65
66 dependencies = [
67 alabaster
68 babel
69 docutils
70 imagesize
71 jinja2
72 packaging
73 pygments
74 requests
75 roman-numerals
76 snowballstemmer
77 sphinxcontrib-applehelp
78 sphinxcontrib-devhelp
79 sphinxcontrib-htmlhelp
80 sphinxcontrib-jsmath
81 sphinxcontrib-qthelp
82 sphinxcontrib-serializinghtml
83 # extra[docs]
84 sphinxcontrib-websupport
85 ]
86 ++ lib.optionals (pythonOlder "3.11") [ tomli ];
87
88 __darwinAllowLocalNetworking = true;
89
90 nativeCheckInputs = [
91 defusedxml
92 pytestCheckHook
93 pytest-xdist
94 typing-extensions
95 writableTmpDirAsHomeHook
96 ];
97
98 disabledTestPaths = lib.optionals isPyPy [
99 # internals are asserted which are sightly different in PyPy
100 "tests/test_extensions/test_ext_autodoc.py"
101 "tests/test_extensions/test_ext_autodoc_autoclass.py"
102 "tests/test_extensions/test_ext_autodoc_autofunction.py"
103 "tests/test_extensions/test_ext_autodoc_automodule.py"
104 "tests/test_extensions/test_ext_autodoc_preserve_defaults.py"
105 "tests/test_util/test_util_inspect.py"
106 "tests/test_util/test_util_typing.py"
107 ];
108
109 disabledTests = [
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 "test_xml_warnings"
125 # racy with too many threads
126 # https://github.com/NixOS/nixpkgs/issues/353176
127 "test_document_toc_only"
128 # Assertion error
129 "test_gettext_literalblock_additional"
130 # Could not fetch remote image: http://localhost:7777/sphinx.png
131 "test_copy_images"
132 # ModuleNotFoundError: No module named 'fish_licence.halibut'
133 "test_import_native_module_stubs"
134 # Racy tex file creation
135 "test_literalinclude_namedlink_latex"
136 "test_literalinclude_caption_latex"
137 # Racy local networking
138 "test_load_mappings_cache"
139 "test_load_mappings_cache_update"
140 "test_load_mappings_cache_revert_update"
141 ]
142 ++ lib.optionals (pythonAtLeast "3.14") [
143 "test_autodoc_special_members"
144 "test_is_invalid_builtin_class"
145 "test_autosummary_generate_content_for_module_imported_members"
146 ]
147 ++ lib.optionals isPyPy [
148 # PyPy has not __builtins__ which get asserted
149 # https://doc.pypy.org/en/latest/cpython_differences.html#miscellaneous
150 "test_autosummary_generate_content_for_module"
151 "test_autosummary_generate_content_for_module_skipped"
152 # Struct vs struct.Struct
153 "test_restify"
154 "test_stringify_annotation"
155 "test_stringify_type_union_operator"
156 ];
157
158 passthru.tests = {
159 inherit breathe;
160 };
161
162 meta = {
163 description = "Python documentation generator";
164 longDescription = ''
165 Sphinx makes it easy to create intelligent and beautiful documentation.
166
167 Here are some of Sphinx’s major features:
168 - Output formats: HTML (including Windows HTML Help), LaTeX (for printable
169 PDF versions), ePub, Texinfo, manual pages, plain text
170 - Extensive cross-references: semantic markup and automatic links for
171 functions, classes, citations, glossary terms and similar pieces of
172 information
173 - Hierarchical structure: easy definition of a document tree, with
174 automatic links to siblings, parents and children
175 - Automatic indices: general index as well as a language-specific module
176 indices
177 - Code handling: automatic highlighting using the Pygments highlighter
178 - Extensions: automatic testing of code snippets, inclusion of docstrings
179 from Python modules (API docs) via built-in extensions, and much more
180 functionality via third-party extensions.
181 - Themes: modify the look and feel of outputs via creating themes, and
182 re-use many third-party themes.
183 - Contributed extensions: dozens of extensions contributed by users; most
184 of them installable from PyPI.
185
186 Sphinx uses the reStructuredText markup language by default, and can read
187 MyST markdown via third-party extensions. Both of these are powerful and
188 straightforward to use, and have functionality for complex documentation
189 and publishing workflows. They both build upon Docutils to parse and write
190 documents.
191 '';
192 homepage = "https://www.sphinx-doc.org";
193 changelog = "https://www.sphinx-doc.org/en/master/changes.html";
194 license = lib.licenses.bsd3;
195 };
196}