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?
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?
Thanks for pointing that out, @jlesquembre! I’ve opened an issue on the nixdoc repository to discuss it.
The following sections have been converted:
The following infrastructure improvements were made:
Visit the CommonMark Docs project and pick a To Do issue today.
Opened a PR converting platform-notes. stdenv/platform-notes: convert to markdown by siraben · Pull Request #106921 · NixOS/nixpkgs · GitHub
I added it to the project. Please @ me if you open any other ones.
@ryantm Can you add this the project? Convert contributing + using section from Docbook to CommonMark · Issue #120011 · NixOS/nixpkgs · GitHub
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:
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.
Special thanks to all these people who’ve been helping convert things since my last update: @blaggacao, @bobby285271, @ngiger, @bryanasdev000, @siraben, @wayofthepie, @jtojnar.
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!
Since the last update, I did the following:
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:
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!
#! /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!
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
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.