Happy Docsgiving 🦃

Announcements
21

Thanks @ryantm, a great initiative.

Some parts of the documentation:

are generated with GitHub - nix-community/nixdoc: Tool to generate documentation for Nix library functions [maintainer=@infinisil]

Is there already a plan to migrate that parts?

22

Thanks for pointing that out, @jlesquembre! I’ve opened an issue on the nixdoc repository to discuss it.

1 Like
23

2020-12-22 Update

The following sections have been converted:

The following infrastructure improvements were made:

Which sections will you convert during your holiday break? :snowman_with_snow: :christmas_tree:

Visit the CommonMark Docs project and pick a To Do issue today.

4 Likes
24

Opened a PR converting platform-notes. stdenv/platform-notes: convert to markdown by siraben · Pull Request #106921 · NixOS/nixpkgs · GitHub

1 Like
25

I added it to the project. Please @ me if you open any other ones.

26

@ryantm Can you add this the project? Convert contributing + using section from Docbook to CommonMark · Issue #120011 · NixOS/nixpkgs · GitHub

27

Docsgiving Update

Nixpkgs manual

It has been a while since I’ve done an update but I’m pleased to announce we are very close eradicating Docbook from the nixpkgs manual!

There are only four main things left to do:

  1. Convert a few more sections in doc/functions. I’ve added issue cards for this on the conversion project. They have detailed instructions, so they should be good first issues for people interested.
  2. Convert the auto-generated nix library function documentation output from Docbook to CommonMark.
  3. Convert the top-level to CommonMark and stop using the CommonMark to Docbook translation layer (that is, pick a CommonMark rendering tool).
  4. Update NixOS website to work with new rendering system.

NixOS manual

There’s also some exciting news here. We’ve merged nixos/doc: add md-to-db.sh, which allows us to start converting the NixOS manual to CommonMark without adding pandoc/GHC to the NixOS build closure. I’ve converted some sections, and I’ll try to start adding some project issues with step-by-step instructions for doing the conversion soon.

Thanks

Special thanks to all these people who’ve been helping convert things since my last update: @blaggacao, @bobby285271, @ngiger, @bryanasdev000, @siraben, @wayofthepie, @jtojnar.

And thanks to the reviewers: @Sandro, @jtojnar, @roberth

14 Likes
28

Update

First of all, thank you to everyone who is providing feedback and help on these efforts, we are making great progress!

You can help the DocBook to CommonMark conversion efforts by grabbing one of the new todo issues in the project!

Nixpkgs Manual

Since the last update, I did the following:

  • finished converting all the last doc/functions sections
  • updated nixdoc to output CommonMark
  • converted all the top-level chapters to CommonMark
  • fixed the graphviz graph

All this work is available at doc: add nixpkgs manual split into multiple pages by ryantm · Pull Request #108063 · NixOS/nixpkgs · GitHub and there is a live demo.

Work left to do:

  1. Improve mmdoc styling to make it acceptable for use
  2. Update NixOS website to work with the new rendering system

NixOS Manual

We’re starting to convert the NixOS manual too and you can help out by grabbing one of the new todo issues in the project!

  • @blaggacao started us off by converting all the release notes to CommonMark!
  • I made a script you can use to review PRs for nixos conversion changes:
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p git meld gitAndTools.gh
set -eou pipefail

trap "kill 0" SIGINT SIGTERM EXIT

PR="$1"

gh pr checkout "$PR"
MB="$(git merge-base HEAD master)"

nix-build nixos/release.nix -A manual.x86_64-linux
CONVERTED_MAN="$(readlink result)"

git checkout master

nix-build nixos/release.nix -A manual.x86_64-linux
MB_MAN="$(readlink result)"

nix-shell -p python3 --run "python3 -m http.server 8000 --directory $MB_MAN/share/doc/nixos" &
nix-shell -p python3 --run "python3 -m http.server 8001 --directory $CONVERTED_MAN/share/doc/nixos" &

sleep 2

"$BROWSER" localhost:8000/
"$BROWSER" localhost:8001/

meld "$MB_MAN/share/doc/nixos/" "$CONVERTED_MAN/share/doc/nixos/" &

sleep 5
read -r -p "Press enter to exit."

Thank you once again for your help and support!

9 Likes
29

I just converted some articles, some are not tracked in the project yet:

https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+author%3Abobby285271+nixos%2Fdoc+is%3Aopen

Thanks in advance for reviewing :grinning:

UPD: most articles in nixos/doc/manual/administration, nixos/doc/manual/configuration, nixos/doc/manual/development, nixos/doc/manual/installation are converted now, except those have <xi:include> included. Not planing to open new PRs in a short period unless there are new todo issues. :wink:

6 Likes