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     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       # Assertion error
 119       "test_gettext_literalblock_additional"
 120       # requires cython_0, but fails miserably on 3.11
 121       "test_cython"
 122       # Could not fetch remote image: http://localhost:7777/sphinx.png
 123       "test_copy_images"
 124     ]
 125     ++ lib.optionals (pythonAtLeast "3.12") [
 126       # https://github.com/sphinx-doc/sphinx/issues/12430
 127       "test_autodoc_type_aliases"
 128     ]
 129     ++ lib.optionals isPyPy [
 130       # PyPy has not __builtins__ which get asserted
 131       # https://doc.pypy.org/en/latest/cpython_differences.html#miscellaneous
 132       "test_autosummary_generate_content_for_module"
 133       "test_autosummary_generate_content_for_module_skipped"
 134       # internals are asserted which are sightly different in PyPy
 135       "test_autodoc_inherited_members_None"
 136       "test_automethod_for_builtin"
 137       "test_builtin_function"
 138       "test_isattributedescriptor"
 139       "test_methoddescriptor"
 140       "test_partialfunction"
 141     ];
 142
 143   meta = {
 144     description = "Python documentation generator";
 145     longDescription = ''
 146       Sphinx makes it easy to create intelligent and beautiful documentation.
 147
 148       Here are some of Sphinx’s major features:
 149       - Output formats: HTML (including Windows HTML Help), LaTeX (for printable
 150         PDF versions), ePub, Texinfo, manual pages, plain text
 151       - Extensive cross-references: semantic markup and automatic links for
 152         functions, classes, citations, glossary terms and similar pieces of
 153         information
 154       - Hierarchical structure: easy definition of a document tree, with
 155         automatic links to siblings, parents and children
 156       - Automatic indices: general index as well as a language-specific module
 157         indices
 158       - Code handling: automatic highlighting using the Pygments highlighter
 159       - Extensions: automatic testing of code snippets, inclusion of docstrings
 160         from Python modules (API docs) via built-in extensions, and much more
 161         functionality via third-party extensions.
 162       - Themes: modify the look and feel of outputs via creating themes, and
 163         re-use many third-party themes.
 164       - Contributed extensions: dozens of extensions contributed by users; most
 165         of them installable from PyPI.
 166
 167       Sphinx uses the reStructuredText markup language by default, and can read
 168       MyST markdown via third-party extensions. Both of these are powerful and
 169       straightforward to use, and have functionality for complex documentation
 170       and publishing workflows. They both build upon Docutils to parse and write
 171       documents.
 172     '';
 173     homepage = "https://www.sphinx-doc.org";
 174     changelog = "https://www.sphinx-doc.org/en/master/changes.html";
 175     license = lib.licenses.bsd3;
 176     maintainers = lib.teams.sphinx.members;
 177   };
 178 }