https://github.com/nix-community/docnix

nix-community reference documentation (until officially released) [maintainer=@hsjobeki]
https://github.com/nix-community/docnix

documentation nix nixos nixpkgs references toolset

Last synced: 3 months ago
JSON representation

nix-community reference documentation (until officially released) [maintainer=@hsjobeki]

• Host: GitHub
• URL: https://github.com/nix-community/docnix
• Owner: nix-community
• Created: 2023-09-12T07:02:14.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-12T23:56:02.000Z (9 months ago)
• Last Synced: 2024-04-15T11:59:32.794Z (9 months ago)
• Topics: documentation, nix, nixos, nixpkgs, references, toolset
• Language: Rust
• Homepage: https://nix-community.github.io/docnix/
• Size: 1.4 MB
• Stars: 25
• Watchers: 3
• Forks: 1
• Open Issues: 10
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Docnix

Finally, complete autogenerated documentation for the whole nix-ecosystem.

## [View here](https://nix-community.github.io/docnix/)

## 🚧🚧🚧 Under Construction 🚧🚧🚧

## Content

Autogenerated documentation from source code including

- `lib.*`

- `pkgs.*`

  - `pkgs.stdenv.*`

- `builtins.*`

## How it works

0. Preparation

For this to work properly we need doc-comments in format according to RFC-145.

Since nixpkgs is not entirely written in this format we use our package *codemod* to automatically migrate all comments.

`Nixpkgs -> Nixpkgs'`

1. Data extraction

The next step is calling our custom `builtins` `unsafeGetAttrDoc` and `unsafeGetLambdaDoc` to retrieve the documentation for all functions in the nixpkgs expression tree.

`Nixpkgs' -> json`

2. Data separation / aggregation

Data is scanned, and additional information from positions, partially applied aliases, etc. is collected and dumped into separate markdown files.

Every markdown file also includes a short `yaml` header needed by the rendering framework.

It contains information about the navigation, tags, headlines and other meta information.

`Json -> Markdown`

3. Rendering

We then utilize a simple javascript rendering framework to transform all the scraped data into separate markdown / html pages.

A search index and sitemap.xml is built for page search as well as for external search engines like Google.

`Markdown -> Static html`

Et voila 🥳

## Contributing / Remaining work

All contributions are welcome! ❤️

- We still need the RFC-145 to be accepted. 👍

- review all the nixpkgs doc-comments changes. 👀

  - This draft [PR#262987](https://github.com/NixOS/nixpkgs/pull/262987) should be split into multiple PRs, reviewed manually and merged. 🔪

- Change the current nixpkgs manual rendering as it will break when using plain markdown in nixpkgs comments. 😱

- Clarify rendering rules / best practices ☝️

  - for aliased functions.

  - for builtins

- Writing more doc-comments  ⌨ ✍️

  - `lib.` `types` and `options` are almost completely undocumented

  - `pkgs.stdenv` is missing some documented functions