nixos/doc: add md-to-db.sh, convert some sections to CommonMark, add 21.11 release notes stub

[ryantm]

Motivation for this change

RFC 72

See the added README and comments in md-to-db.sh for motivation too.

[flokli]

I don't think this should be merged as-is until we have tooling to ensure programmatically (enforced Github Actions maybe?) there's no different versions of the two different versions.

Alternatively, if most of the migration is done by a script anyways, we could also have a long-living PR migrating ALL documentation at once, rebased every once and then, and on merge removing the docbook files it converted from.

[ryantm]

I don't think this should be merged as-is until we have tooling to ensure programmatically (enforced Github Actions maybe?) there's no different versions of the two different versions.

I've added a GitHub Action to this PR to enforce consistency in the generated Markdown files.

For reference:

• a success run https://github.com/NixOS/nixpkgs/runs/1603678811?check_suite_focus=true
• a failure run https://github.com/NixOS/nixpkgs/runs/1603684254?check_suite_focus=true

[ryantm]

@Floki maybe in light of the progress on #108063 you'd be okay with merging this so we can start working on converting the NixOS manual to CommonMark.

[ryantm]

@jonringer and I talked and he 21.11 release notes to be in Markdown, so I think after the 21.05 branch off we should merge this and create those release notes in Markdown. I can try to update this so it adds the release note stub file too.

[ryantm]

I've updated this to convert the "contributing to this manual" section (mentioning the need to run the md-to-db.sh script, and added the 21.11 release notes stub.

[jonringer]

thanks for the release stub. Changes look great :)

[jonringer]

The time has come!

[zowoq]

Just an FYI as actions have changed since the PR was opened: this won't run automatically for first time contributors so it's possible that the docs could drift out of sync.

https://github.blog/2021-04-22-github-actions-update-helping-maintainers-combat-bad-actors/

Would need to do the same as we did in 5ba2e4e (pull_request_target, permissions:, and the PR merge ref) to make it run unconditionally.

[jonringer]

ah, great point.

[nixos-discourse]

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

https://discourse.nixos.org/t/happy-docsgiving/10214/27