pkgs/development/python-modules/sphinx/default.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   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
  41 buildPythonPackage 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     tag = "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 }