nixpkgs manual: Python chapter structural problems

[alejandrosame]

Problem

The Python chapter in nixpkgs manual is hard to navigate and use. The Documentation team has agreed to follow the Diátaxis framework as a methodology to improve our documentation. Diátaxis defines what constitutes as reference, how-to and explanation material.

With this context, it is clear that the Python section mixes all these types of contents and does not stick to a unified style. The next subsection shows the outline in unstable (https://github.com/NixOS/nixpkgs/commit/3acb5c4264c490e7714d503c7166a3fde0c51324) with an assessment of the type of documentation that is predominant in a given heading.

Tagged outline

Each subsection is tagged with Reference, How-to and Explanation according to the definitions linked earlier in this issue.

• User Guide How-to

  User Guide subsections skipped to save space. They are all predominantly How-to

• Reference

  • Interpreters Reference
  • Missing Tkinter module standard library Reference
  • Attributes on interpreters packages Reference
  • Optimizations How-to
  • Building packages and applications Reference
  • buildPythonPackage function
    • buildPythonPackage parameters
    • overriding Python packages
  • Optional extra dependencies How-to
  • buildPythonApplication function
  • toPythonApplication function
  • toPythonModule function
  • python.buildEnv function
    • python.buildEnv arguments
  • python.withPackages function
  • Setup hooks
  • Development mode
  • Tools Explanation
  • Deterministic builds Explanation
  • Automatic tests How-to
  • Common issues How-to

• FAQ

  • How to solve circular dependencies? How-to
  • How to override a Python package? How-to
  • python setup.py bdist_whell cannot create .whl How-to
  • install_data / data_files problems How-to
  • Rationale of non-existent global site-packages Explanation
  • How to consume Python modules using pip in a virtual environment like I am used to on other Operating Systems? How-to
  • How to override a Python package from configuration.nix? How-to
  • How to override a Python package using overlays? How-to
  • How to override a Python package for all Python versions using extensions? How-to
  • How to use Intel’s MKL with numpy and scipy? How-to
  • What inputs do setup_requires, install_requires and tests_require map to? Reference?

• Contributing How-to, guidelines, policy

  • Contributing guidelines

• Package set maintenance Explanation and How-to

  • Updating packages in bulk How-to and guidelines

• CPython Update Schedule Explanation, policy

Proposal

The Python section in the nixpkgs manual should stick to Reference content. In order to achieve this goal incrementally, the following course of action is proposed:

• [x] Move non-Reference content out of the Reference subsection. https://github.com/NixOS/nixpkgs/pull/247117
• [x] Move Reference subsection to the top of the Python chapter. https://github.com/NixOS/nixpkgs/pull/247117

After taking these actions, the Python section will have two clearly distinct content blocks: the reference section, and content that is further from being reference material. These changes should keep content in the current single Markdown file.

At this point, it should be easier to proceed per individual section:

• [ ] Add content from Explanation/How-to section that is missing from Reference.
• [ ] Find a home for Explanation/How-to section and move it accordingly.
• [ ] Rinse and repeat until there is only reference material in the Python chapter.

Related

• https://github.com/NixOS/nixpkgs/issues/240118
• https://github.com/NixOS/nix/issues/7769 (The main problems with the Python chapter are shared across manuals).

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-03-documentation-team-meeting-notes-69/31263/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-17-documentation-team-meeting-notes-73/31853/1

[fricklerhandwerk]

Regarding the hooks documentation, we discussed with the @NixOS/documentation-team a while ago whether it would make sense to extract the documentation comments and strip them from the build to avoid mass rebuilds when editing them. It needs some research whether it's meaningful, and @roberth suggested that in the meantime we could just add .md files next to the hooks.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-23-documentation-team-meeting-notes-75/32142/1