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.

Sign up for GitHub

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

Jump to bottom

Harmonize docbook build experience #68199

Closed
jtojnar opened this issue Sep 6, 2019 · 2 comments
Closed

Harmonize docbook build experience #68199

jtojnar opened this issue Sep 6, 2019 · 2 comments
Labels
0.kind: enhancement Add something new 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md 6.topic: documentation Meta-discussion about documentation and its workflow

Comments

@jtojnar
Copy link
Member

jtojnar commented Sep 6, 2019

While DocBook is pretty great for a software product, our documentation workflow is not. One of the issues is the ease of building the docs – normally the user would just open a nix-shell in the relevant directory and then call make to build the HTML output, this is not the case everywhere.

It is not sufficient to provide commands like nix-build nixos/release.nix -A manual.x86_64-linux in a README, since it is not fine-grained enough, slow and hard to remember.

Currently, we have a somewhat working Makefile in doc (Nixpkgs docs) but the one in nixos/doc/manual only contains a small number of targets and none for producing HTML. We should come up with a single set of targets that would be available in every Nix-related docs.
@jtojnar jtojnar added 0.kind: enhancement Add something new 6.topic: documentation Meta-discussion about documentation and its workflow labels Sep 6, 2019
@stale stale bot added the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Jun 2, 2020
@NixOS NixOS deleted a comment from stale bot Jun 2, 2020
@jtojnar
Copy link
Member Author

jtojnar commented Jun 2, 2020

Still something I would like to tackle when I find time.

@jtojnar
Copy link
Member Author

jtojnar commented Dec 5, 2020 •
edited
Loading

We are moving away from DocBook (NixOS/rfcs#72) so it no longer makes sense to invest time into this.

@jtojnar jtojnar closed this as completed Dec 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
0.kind: enhancement Add something new 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md 6.topic: documentation Meta-discussion about documentation and its workflow
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@jtojnar