Commit Graph

48 Commits

Author SHA1 Message Date
Adam Joseph
ed312cb4f7
doc/default.nix: make the manual build on more than one core (#225921)
* doc/default.nix: make the manual build on more than one core

Let's build the manual with more than one core.  Maybe people will take better care of it now that it is less painful to build.
2023-04-25 14:37:50 +02:00
pennae
d041641b1a nixos/manual: remove md-to-db
with manual chapters no longer needing pandoc for their conversion to
xml we can get rid of this source of confusion, and its huge cache of
xml files.
2023-02-10 06:40:15 +01:00
Naïm Favier
a8d4cf149c
doc: separate manpage URLs from the Pandoc filter
Move the manpage-to-URL mapping to `doc/manpage-urls.json` so that we can
reuse that file elsewhere, and generate the `link-manpages.lua` filter from
that file.

Also modify the Pandoc filter so that it doesn't wrap manpages that are
already inside a link.

Keeping a Lua filter is essential for speed: a Python filter would
increase the runtime `md-to-db.sh` from ~20s to ~30s (but Python is not
to blame; marshalling Pandoc types to and from JSON is a costly operation).
Parsing in Lua seems tedious, so I went with the Nix way.
2023-01-02 14:11:22 +01:00
Jan Tojnar
da95ab11b4 doc: Add helper for converting DocBook files to Markdown 2021-07-13 02:21:22 +02:00
Jan Tojnar
04b59b0328 doc: Linkify man page references 2021-07-13 02:21:22 +02:00
Jan Tojnar
c9139dfa1a doc: Add support for MyST roles
Officially, only the manpage role is supported at the moment.

Unlike in rST, the syntax uses braces instead of colons:

    {manpage}`nix.conf(5)`
2021-07-13 02:10:57 +02:00
Jan Tojnar
a49d36b979 doc: Move lua filters to subdirectory 2021-07-12 22:57:28 +02:00
Jan Tojnar
f07dcbef64
nixos/doc: Synchronize the Markdown generator with Nixpkgs
Switch to CommonMark with our extensions.
2021-06-18 00:07:00 +02:00
Ryan Mulligan
740d9fe090
Merge pull request #125671 from SFrijters/doc-improve-make-clean
doc: Clean up generated media directory
2021-06-12 16:51:03 -07:00
Jan Tojnar
3c78ad2561
doc: Use markdown syntax for xrefs
Syntax is taken from MyST:

https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
2021-06-07 06:34:59 +02:00
Jan Tojnar
adecb00f5a
doc: Build as CommonMark
We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool.

Since RFC 0072 agreed on CommonMark, let’s switch to that.

We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-07 06:34:59 +02:00
Stefan Frijters
c9ecf037ec
doc: Clean up generated media directory
pandoc uses ./media to extract media files - add it to the list
of directories that need to be removed by `make clean`.
2021-06-04 15:03:46 +02:00
Robert Hensing
0a4a486096 doc/README.md: init 2021-03-04 18:10:39 +01:00
Jan Tojnar
ba11a96653
doc: Add staging workflow diagram 2020-12-09 05:26:55 +01:00
Jan Tojnar
64b8489d54
doc: clean up makefile
The sectn and ulink hacks are not necessary since pandoc has been defaulting to Docbook 5 for a long time.
With the pandoc patches, we can get rid of id→xml:id replacement and xmlns hacks as well.
2020-12-07 23:49:56 +01:00
Mitsuhiro Nakamura
c9c6f5f693 doc: fix MD_TARGETS
globstar (**) does not work in Makefile
2020-07-18 14:23:25 +09:00
Vladimír Čunát
83015ff795
nixpkgs manual: fix build after pandoc(?) update
I din't try to pinpoint the exact commit, but we started getting:
> The extension smart is not supported for docbook
Reading pandoc docs, I can't see what use to us "smart" could be
when writing the in-between docbook (to be converted to html).
https://pandoc.org/MANUAL.html#extension-smart
2020-03-02 08:24:54 +01:00
Graham Christensen
fa47df6174
doc: move parameters to an XML file 2019-07-04 09:16:06 -04:00
Graham Christensen
5a0696f6d0
xmlformat.conf: move to doc-support build 2019-07-04 09:10:14 -04:00
Graham Christensen
de58e706f9
docs: Get highlightjs from build symlink 2019-07-04 09:10:14 -04:00
Graham Christensen
35262ba6a7
docs: get XSL from build / symlink 2019-07-04 09:10:13 -04:00
Graham Christensen
e65c2c6672
docs: find docbook rng from doc-support 2019-07-04 09:10:13 -04:00
Graham Christensen
d11f5a9d15
docs: get version from doc-support build 2019-07-04 09:10:13 -04:00
Graham Christensen
cd6bf8aa00
docs: use a single nix-build for all the generate function docs 2019-07-04 09:07:47 -04:00
John Ericson
3b27113a7c manual: Make sure building doesn't need recursive nix
$(shell ...) looks a little sketch like it will be run no matter what.
And there are problems building the manual on darwin so hopefully this
fixes them.
2019-03-24 22:11:09 -04:00
Vincent Ambo
29c320f9a6 doc: Include function doc generation in Makefile
Since #53055 was merged the Makefile for the manual could not be run
correctly as the generated function documentation was included, but
not actually generated.

This adds the necessary generation step by first building the XML file
containing function locations and preserving its store path in a
variable, which is then used both for linking of the locations file
and as a build input for the function docs generator.

This fixes #55014
2019-02-01 11:45:30 +01:00
danbst
663b8cc929 manual: document ways of obtaining source hashes
... and security nuances
2019-01-11 02:06:52 +02:00
Graham Christensen
5daee73ce4
Generate links to function definitions
Hydra passes the full revision in to the input, which we pass through.

If we don't get this ,we try to get it from other sources, or default to
master which should have the definition in a close-ish location.

All published docs should have theURL resolve properly, only local
hackers will have the link break.
2018-10-05 11:20:46 -04:00
Graham Christensen
f835f77e02
nixpkgs: Start documenting library functions in XML
Covers assert functions and about half of the attrsets functions.

Some internal consistency around IDs could be improved.
2018-10-05 10:06:08 -04:00
Graham Christensen
444e04b985
nixpkgs docs: Rebuild manual-full if nested XML docs change 2018-10-02 15:59:00 -04:00
Samuel Dionne-Riel
bc0421c4cf doc: Adds xml fixing script. (see previous and next commits)
This script is used to automatically fix issues within xml documentation
files.

The script is *for now* intended to be used ad-hoc, and the commits to
be examined.

A future discussion will define whether:

  * This commit and scripts are kept.
  * The script is extended for common use.

The biggest issue right now with the script is that it *could* in theory
destroy a valid space-less varlistentry.

The script could, in practical use, be changed and extended to normalize
some parts of the XML files, mainly:

  * A common quoting style for attributes
  * Fix-up some weird formatting automatically that xmlformat doesn't
    catch
2018-05-31 21:02:15 -04:00
Graham Christensen
ab1648bf0d
nixpkgs doc: add format Make target 2018-04-30 22:37:58 -04:00
Maximilian Bosch
9274ea3903
treewide: rename version attributes
As suggested in https://github.com/NixOS/nixpkgs/pull/39416#discussion_r183845745
the versioning attributes in `lib` should be consistent to
`nixos/version` which implicates the following changes:

* `lib.trivial.version` -> `lib.trivial.release`
* `lib.trivial.suffix` -> `lib.trivial.versionSuffix`
* `lib.nixpkgsVersion` -> `lib.version`

As `lib.nixpkgsVersion` is referenced several times in `NixOS/nixpkgs`,
`NixOS/nix` and probably several user's setups. As the rename will cause
a notable impact it's better to keep `lib.nixpkgsVersion` as alias with
a warning yielded by `builtins.trace`.
2018-04-28 14:23:53 +02:00
Graham Christensen
8f33464ca7
nixos docs: syntax highlight
- Rectifies diverging CSS by combining
   nixos/nixpkgs docs CSS
 - Moves our custom Highlight.js loader in to
   the hljs package
 - Switches the nixos docs to use SVG
   callouts too
2018-04-05 07:54:01 -04:00
Graham Christensen
8dac5ce146
nixpkgs docs: syntax highlight 2018-03-26 21:44:24 -04:00
Graham Christensen
da17974541
Move the overridden CSS to overrides.css which can be applied on nixos.org 2018-03-26 14:45:00 -04:00
Graham Christensen
a80856cec5
nixpkgs docs: Use SVGs for callouts 2018-03-26 14:08:36 -04:00
Graham Christensen
67f9d2425d
Add 'make debug' to call xmloscopy 2018-03-25 20:01:31 -04:00
Graham Christensen
fce1fb7e75
Move validate to top-level so it doesn't rebuild the outputs every time 2018-03-25 19:52:08 -04:00
Graham Christensen
30dd2d3feb
Validate when building outputs 2018-03-25 19:52:08 -04:00
Graham Christensen
7e25ff7106
docs: Build with a makefile 2018-03-25 19:52:07 -04:00
Eelco Dolstra
438b9c543d Nixpkgs manual: Add a Nix expression to build 2014-08-24 11:03:55 +02:00
Eelco Dolstra
2737291b5d Manual: html -> xhtml 2014-07-03 12:37:40 +02:00
Eelco Dolstra
d877e7b40f * Build a PDF of the manual.
svn path=/nixpkgs/trunk/; revision=16316
2009-07-10 13:41:47 +00:00
Eelco Dolstra
85a9971e96 * Manual outline.
svn path=/nixpkgs/trunk/; revision=12057
2008-06-12 13:10:11 +00:00
Eelco Dolstra
bd0e895bad * Release notes.
* Linux 2.6.22.6.
* w3m 0.5.2.

svn path=/nixpkgs/trunk/; revision=9305
2007-09-11 20:05:54 +00:00
Eelco Dolstra
921c08c7b3 * Start of Nixpkgs 0.10 release notes.
svn path=/nixpkgs/trunk/; revision=6676
2006-10-06 13:37:31 +00:00
Eelco Dolstra
6eff2a5ff8 * NEWS in DocBook.
svn path=/nixpkgs/trunk/; revision=4627
2006-01-30 17:34:34 +00:00