Render Markdown in option docs for flakes and longDescription #539

ncfavier · 2022-09-09T21:56:15Z

Closes #535, closes #525

To do:

We're currently creating a new temporary file containing the xref lua filter for each Pandoc invocation. This is bad. I think it would generally be nicer to package the files we need (pandoc filters, flake_info.nix) alongside flake-info: we could set a DATADIR variable in the Nix build that is detected at compile time and, if unset, defaults to CARGO_MANIFEST_DIR so that cargo run still finds the files.
The pandoc crate does not let us define precisely the flavour of Markdown we want (Commonmark with a few extensions) because it does not expose all of Pandoc's formats and extensions (notably commonmark_x and +fenced_divs). For now I've set the format to markdown, which is hopefully a superset, but if finer control is needed we will have to ~~invoke pandoc directly~~ or fork the crate. At least manpage references seem to render fine. Ping @jtojnar @pennae
There seems to be a regression with nix-security. EDIT: this is a bug exposed by making FlakeEntry tagged: we don't support multiple licenses in flake packages, so previously flake packages with a list of licenses were parsed as apps instead.

github-actions · 2022-09-09T21:57:32Z

🚀 Deployed on https://632899fb7bd5b614cc23836f--nixos-search.netlify.app

pennae · 2022-09-09T22:14:06Z

flake-info/src/data/pandoc.rs

+        let roles_filter = Path::new(FILTERS_PATH).join("myst-reader/roles.lua");
+        let man_filter = Path::new(FILTERS_PATH).join("link-unix-man-references.lua");


docbook-writer/rst-roles.lua defines additional roles for MD option docs that may be useful here (though probably not vital).

But we're writing HTML, not DocBook.

yes, but if you previously rendered eg envar and literal differently you'll probably have to handle those roles to not render them all the same way. (haven't checked, just guessing that this may happen)

Right, we didn't do anything like that.

ncfavier · 2022-09-10T14:53:05Z

Ah, markdown requires a blank line before lists whereas commonmark doesn't. That settles it, let's switch to commonmark.

Extension list taken from nixpkgs/doc/Makefile.

ncfavier · 2022-09-19T17:28:29Z

I've added Markdown rendering for longDescription.

As a reminder/note to self, XSS sanitisation is done by Elm.

ncfavier · 2022-10-14T16:04:25Z

@ysndr ping

ncfavier · 2022-10-18T10:01:45Z

(or @garbas)

ysndr · 2022-10-28T12:41:17Z

Looks good, and brings in some welcome cleanup
Thank you @ncfavier
Is there a way to see the result in the preview?

ncfavier · 2022-10-28T13:48:43Z

Is there a way to see the result in the preview?

You can look at tmux or geomyidae.

ncfavier · 2022-10-28T14:01:19Z

Ah, I shouldn't have merged so soon. The nixpkgs-unstable import is currently broken (but a fix is underway), so that channel will be rolled back a bit until the next update.

Also it seems like the flake import is hitting GitHub API rate limits. Fix: #553

github-actions bot temporarily deployed to pull request September 9, 2022 21:57 Inactive

Render Markdown option docs in flakes

343026c

ncfavier force-pushed the markdown-options branch from a648164 to 343026c Compare September 9, 2022 22:00

github-actions bot temporarily deployed to pull request September 9, 2022 22:01 Inactive

Bump VERSION

339a4a4

github-actions bot temporarily deployed to pull request September 9, 2022 22:05 Inactive

pennae reviewed Sep 9, 2022

View reviewed changes

Allow multiple licenses for flake packages

f68daa2

github-actions bot temporarily deployed to pull request September 9, 2022 22:58 Inactive

ncfavier marked this pull request as ready for review September 10, 2022 14:20

github-actions bot temporarily deployed to pull request September 10, 2022 14:21 Inactive

Bundle assets with flake-info instead of using temp files

4c8e53a

ncfavier force-pushed the markdown-options branch from a8ff1ed to 4c8e53a Compare September 10, 2022 14:24

github-actions bot temporarily deployed to pull request September 10, 2022 14:25 Inactive

github-actions bot temporarily deployed to pull request September 10, 2022 16:56 Inactive

ncfavier force-pushed the markdown-options branch from e7af813 to 74d1f12 Compare September 10, 2022 16:59

github-actions bot temporarily deployed to pull request September 10, 2022 17:01 Inactive

ncfavier requested review from ysndr and garbas September 10, 2022 17:15

ncfavier changed the title ~~Render Markdown option docs in flakes~~ Render Markdown option docs for flakes Sep 10, 2022

ncfavier force-pushed the markdown-options branch from 74d1f12 to 2d69ea5 Compare September 12, 2022 10:15

github-actions bot temporarily deployed to pull request September 12, 2022 10:16 Inactive

Switch to Commonmark

601ae37

Extension list taken from nixpkgs/doc/Makefile.

ncfavier force-pushed the markdown-options branch from 2d69ea5 to 601ae37 Compare September 13, 2022 11:26

github-actions bot temporarily deployed to pull request September 13, 2022 11:27 Inactive

Render meta.longDescription as Markdown

b53b943

github-actions bot temporarily deployed to pull request September 19, 2022 16:34 Inactive

ncfavier changed the title ~~Render Markdown option docs for flakes~~ Render Markdown in option docs for flakes and longDescription Sep 19, 2022

ncfavier mentioned this pull request Oct 28, 2022

try to bring back the CI #552

Closed

ysndr approved these changes Oct 28, 2022

View reviewed changes

ncfavier merged commit ba0b05b into main Oct 28, 2022

ncfavier deleted the markdown-options branch October 28, 2022 13:49

fricklerhandwerk mentioned this pull request Nov 5, 2022

Generated setup hooks documentation NixOS/nixpkgs#197070

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Render Markdown in option docs for flakes and longDescription #539

Render Markdown in option docs for flakes and longDescription #539

ncfavier commented Sep 9, 2022 •

edited

Loading

github-actions bot commented Sep 9, 2022 •

edited

Loading

pennae Sep 9, 2022

ncfavier Sep 9, 2022

pennae Sep 9, 2022 •

edited

Loading

ncfavier Sep 9, 2022

ncfavier commented Sep 10, 2022

ncfavier commented Sep 19, 2022

ncfavier commented Oct 14, 2022

ncfavier commented Oct 18, 2022

ysndr commented Oct 28, 2022

ncfavier commented Oct 28, 2022

ncfavier commented Oct 28, 2022 •

edited

Loading

		let roles_filter = Path::new(FILTERS_PATH).join("myst-reader/roles.lua");
		let man_filter = Path::new(FILTERS_PATH).join("link-unix-man-references.lua");

Render Markdown in option docs for flakes and longDescription #539

Render Markdown in option docs for flakes and longDescription #539

Conversation

ncfavier commented Sep 9, 2022 • edited Loading

github-actions bot commented Sep 9, 2022 • edited Loading

pennae Sep 9, 2022

Choose a reason for hiding this comment

ncfavier Sep 9, 2022

Choose a reason for hiding this comment

pennae Sep 9, 2022 • edited Loading

Choose a reason for hiding this comment

ncfavier Sep 9, 2022

Choose a reason for hiding this comment

ncfavier commented Sep 10, 2022

ncfavier commented Sep 19, 2022

ncfavier commented Oct 14, 2022

ncfavier commented Oct 18, 2022

ysndr commented Oct 28, 2022

ncfavier commented Oct 28, 2022

ncfavier commented Oct 28, 2022 • edited Loading

ncfavier commented Sep 9, 2022 •

edited

Loading

github-actions bot commented Sep 9, 2022 •

edited

Loading

pennae Sep 9, 2022 •

edited

Loading

ncfavier commented Oct 28, 2022 •

edited

Loading