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