Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: introduce fact injection workflow #313095

Closed

Conversation

alejandrosame
Copy link
Member

Introduce a workflow to extract documentation fragments from the nixpkgs tree. This way, we can encourage the autogeneration of documentation for sections that desync easily, such as the existing Python interpreters for a given nixpkgs version.

This workflow is introduced in a manual fashion. The contributor willing to autogenerate some fragment has to provide with a fact.target indicating the file where to look for a line <!-- FACT ${fact.id} -->, which will be substituted with the contents of fact.drv before calling nixos-render-docs.

From this point, we can work on further automation/convenience. For example, nixos-render-docs could be extended to accept an include block facts that looks for autogenerated fragments, which will potentially give better feedback to contributors.

Future work

  • Add a (proper) generator for python-interpreter-table.

I have a working function already, but needs code and comment refactoring. It could be included as another commit

  • Add testing framework to the current workflow.
  • Make a roadmap to extend nixos-render-docs with this workflow.

Introduce a workflow to extract documentation fragments from the nixpkgs tree.
This way, we can encourage the autogeneration of documentation for
sections that desync easily, such as the existing Python interpreters
for a given nixpkgs version.

This workflow is introduced in a manual fashion. The contributor
willing to autogenerate some fragment has to provide with a
`fact.target` indicating the file where to look for a line `<!-- FACT
${fact.id} -->`, which will be substituted with the contents of `fact.drv`
before calling `nixos-render-docs`.

From this point, we can work on further automation/convenience. For
example, `nixos-render-docs` could be extended to accept an include
block `facts` that looks for autogenerated fragments, which will
potentially give better feedback to contributors.
@alejandrosame alejandrosame self-assigned this May 20, 2024
@alejandrosame alejandrosame added the 6.topic: documentation Meta-discussion about documentation and its workflow label May 20, 2024
@fricklerhandwerk
Copy link
Contributor

I think we can close this, since the Python table generation is but one sample for how to do it, and we can abstract over it once there's need.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

2 participants