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