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

dockertools: Update doc to use CommonMark #108914

Merged
merged 4 commits into from Mar 4, 2021
Merged

dockertools: Update doc to use CommonMark #108914

merged 4 commits into from Mar 4, 2021

Conversation

bryanasdev000
Copy link
Member

Motivation for this change

Closes #105759.

Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Ensured that relevant documentation is up to date
  • Fits CONTRIBUTING.md.

@bryanasdev000
Copy link
Member Author

For now this PR have two problems, already described here #105759 (comment).

@roberth
Copy link
Member

roberth commented Jan 18, 2021

It seems like the anchors are missing. I don't know what's the right way to create the anchors for the examples, but perhaps we can insert docbook syntax for it, similar to HTML.

I couldn't find anything about the {anchor} syntax suggested for headers here in the spec either.

@ryantm what's the best way to create anchors for examples?

...
warning: failed to load external entity "functions/library/generated/overrides/lib.options.showOption.xml"
jing doc-support/result/docbook.rng manual-full.xml
/build/doc/manual-full.xml:13148:59: error: IDREF "ex-dockerTools-buildImage-runAsRoot" without matching ID
/build/doc/manual-full.xml:12728:49: error: IDREF "ex-dockerTools-buildImage" without matching ID
make: *** [Makefile:29: validate] Error 1
builder for '/nix/store/yajds5xax6hjdjdqm4y23xvkvhpbr36r-nixpkgs-manual.drv' failed with exit code 2
error: build of '/nix/store/yajds5xax6hjdjdqm4y23xvkvhpbr36r-nixpkgs-manual.drv' failed

For this I tried (see <xref linkend="ex-dockerTools-buildImage"/>) per #105243 but build fails with same error.

Any help is appreciated.

@ryantm
Copy link
Member

ryantm commented Jan 18, 2021

@roberth We are using Pandoc's Bracketed Spans extension. It seems like it has decent popular support on the CommonMark forums: https://talk.commonmark.org.

You can add an anchor anywhere with []{#anchor-id}, which we are doing in the GNOME section currently.

@bryanasdev000
Copy link
Member Author

It seems like the anchors are missing. I don't know what's the right way to create the anchors for the examples, but perhaps we can insert docbook syntax for it, similar to HTML.

I couldn't find anything about the {anchor} syntax suggested for headers here in the spec either.

@ryantm what's the best way to create anchors for examples?

...
warning: failed to load external entity "functions/library/generated/overrides/lib.options.showOption.xml"
jing doc-support/result/docbook.rng manual-full.xml
/build/doc/manual-full.xml:13148:59: error: IDREF "ex-dockerTools-buildImage-runAsRoot" without matching ID
/build/doc/manual-full.xml:12728:49: error: IDREF "ex-dockerTools-buildImage" without matching ID
make: *** [Makefile:29: validate] Error 1
builder for '/nix/store/yajds5xax6hjdjdqm4y23xvkvhpbr36r-nixpkgs-manual.drv' failed with exit code 2
error: build of '/nix/store/yajds5xax6hjdjdqm4y23xvkvhpbr36r-nixpkgs-manual.drv' failed

For this I tried (see <xref linkend="ex-dockerTools-buildImage"/>) per #105243 but build fails with same error.
Any help is appreciated.

@roberth We are using Pandoc's Bracketed Spans extension. It seems like it has decent popular support on the CommonMark forums: https://talk.commonmark.org.

You can add an anchor anywhere with []{#anchor-id}, which we are doing in the GNOME section currently.

Will try, this is the same case for ocitools and snaptools.

@bryanasdev000
Copy link
Member Author

Guys, sorry for taking so long.

@bryanasdev000 bryanasdev000 marked this pull request as ready for review February 16, 2021 00:13
bryanasdev000 and others added 4 commits March 4, 2021 17:18
@bryanasdev000 @roberth
doc/builders/images/dockertools.xml: Convert to markdown and start im…
4b99dbb 
…provements

Need to verify things like `error: IDREF "" without matching ID` and `::: {.note}`

Signed-off-by: Bryan A. S <bryanasdev000@gmail.com>
@bryanasdev000 @roberth
doc/builders/images/dockertools.section.md: Indent nix code
06e40b3 
Signed-off-by: Bryan A. S <bryanasdev000@gmail.com>
@bryanasdev000 @roberth
doc/builders/images/dockertools.section.md: Fix anchor errors
5a1a08c 
Also change note notation

Signed-off-by: Bryan A. S <bryanasdev000@gmail.com>
@roberth
doc/builders/images/dockertools.section.md: Fix link labels
a1cf35f
roberth
roberth approved these changes Mar 4, 2021
View reviewed changes
Copy link
Member

@roberth roberth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebased and fixed two labels. Looks good!

@roberth roberth merged commit 16b327c into NixOS:master Mar 4, 2021
@roberth
Copy link
Member

roberth commented Mar 4, 2021

Thanks @bryanasdev000 !

@bryanasdev000 bryanasdev000 deleted the doc-dockertools branch May 3, 2021 20:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@roberth roberth roberth approved these changes

@ryantm ryantm Awaiting requested review from ryantm

Assignees
No one assigned
Labels
8.has: documentation 10.rebuild-darwin: 0 10.rebuild-linux: 0
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Convert dockertools from Docbook to CommonMark
3 participants
@bryanasdev000 @roberth @ryantm