Commit graph

99 commits

Author SHA1 Message Date
eldritch horrors 725f5cd358 docs: redo content generation for mdbook and manual
manpages can be rendered using the markdown output of mdbook, the rest
of the manual can generated out of the main doc/manual source tree. we
still use lowdown to actually render manpages instead of eg mdbook-man
because lowdown does generate reasonably good manpages (though that is
also somewhat debatable, but they're a lot better than mdbook-man).

doing this not only lets us drastically simplify the lowdown pipeline,
but also remove all custom {{#include}} handling since now mdbook does
all of it, even for the manpage builds. even the lowdown wrapper isn't
entirely necessary because lowdown can take all wrapper arguments with
command line flags rather than bits of input file content.

This also implements running mdbook in Meson, in order to generate the
manpages. The mdbook outputs are also installed in the usual location.

Co-authored-by: Qyriad <qyriad@qyriad.me>

Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-11 13:32:06 +00:00
eldritch horrors e6aab36d60 docs: put the manual build into a known tmpdir
this isn't strictly necessary, but it'll make it a lot easier to put the
generated files used by the autoconf build system in this directory too.
doing this now already will make the meson transition a lot easier later

Change-Id: I5fb39eade2ff88b6093c9ee436c9e8db793e9448
2024-04-09 02:09:36 +00:00
eldritch horrors c1ae35d34a docs: don't compute SUMMARY.md during build
this would make meson build compatibility unnecessarily hard and
the cli does not change often enough to justify this complexity.

Change-Id: I17b1870cdf8538feeaa01a9945db97af2175a642
2024-04-09 02:09:36 +00:00
eldritch horrors d9bc197ff4 docs: don't compute rl-next.md during build
not sure why this was done the way it was considering that includes are
a feature the doc toolchain had previously. let's just always have some
kind of entry for the upcoming release in the dev manual builds even if
that means having a completely empty release notes chapter.

the release notes generation script isn't entirely functional right now
due to pre-commit hooks, but it's good enough for time being. we need a
better release process for notes anyway.

Change-Id: Ifda6912cf5233db013f72a30247a62d6f22b1565

Change-Id: I9eb347ec4aabc5be2b816ff0fd3e4be45f93b934
2024-04-09 02:09:36 +00:00
eldritch horrors 07ef9f9f5d docs: skip do custom include processing for mdbook
mdbook already does include processing of its own, and the custom
processing code has always admitted as much. we don't need it for
the mdbook build at this point if we run our preprocessors in the
right order, and maybe we can even have mdbook to return complete
pages to us that we only have to pass to lowdown without any more
preprocessing of our own.

Change-Id: Icd978acbc3b1e215fee8f062c53ab2cb2a222ab1
2024-04-09 02:09:36 +00:00
Qyriad c355354772 docs: replace sed invocation with an mdbook preprocessor for @docroot@
We're not entirely clear on why the links preprocessor has to be done
*before* rather than after, but we assume it is probably that as a
builtin preprocessor it does some processing on the raw book source,
and not just the JSON data.

Also a real use for Python pattern matching? I know I was surprised too.

Change-Id: Ibe8b59e7b5bd5f357a655d8b4c5f0b0f58a67d6b
2024-04-04 21:43:19 +00:00
eldritch horrors d2aca15f31 doc: remove the -- unescaping hack
lowdown has an option to disable this behavior. use it.

Change-Id: I06d4201b7f528021ddb8e94ac6baff385402e080
2024-04-01 20:15:28 +00:00
eldritch horrors 65d544b1a6 build: extract make "functions" into scripts
we'll want to use these for the meson builds, and probably eventually
rewrite them in something that isn't plain shell. diffoscope confirms
that out/share and doc/share are equal before and after these changes

Change-Id: I49aa418fc8615cad86d67328e08c28a7405ec952
2024-03-30 14:26:47 +00:00
eldritch horrors 279e30e7ef build: replace changelog-d with local script
hacking changelog-d to support not just github but also forgejo and
gerrit is a lot more complicated than it's worth, even moreso since
the entire thing can just as well be done with ~60 lines of python.
this new script is also much cheaper to instantiate (being python),
so having it enabled in all shells is far less of a hassle.

we've also adjusted existing release notes that referenced a gerrit
cl to auto-link to the cl in question, making the diff a bit bigger

closes lix-project/lix#176

Change-Id: I8ba7dd0070aad9ba4474401731215fcf5d9d2130
2024-03-27 03:09:14 +00:00
eldritch horrors e8f1acfb18 Merge pull request #5145 from fedepell/local_doc_build_5140
Docs build: depend on locally built nix executable and not installed one

(cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd)

===

includes changes from (because not doing so removes manpages):

Merge pull request #9976 from alois31/restore-manual-pages

Restore manual pages

(cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4)

Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 23:01:05 +01:00
eldritch horrors e8a488236c Merge pull request #9393 from hercules-ci/changelog-d
Automatically compile hand-written release notes with `changelog-d`

(cherry picked from commit 928f0c13414d20c1af88b30bd6700fd730ee0bab)
Change-Id: Ia0685835c52edf185b64dd696b19305746c077e5
2024-03-04 07:11:19 +01:00
Valentin Gagarin a68bf15fe6 backport fix for the --help output 2023-11-10 19:22:42 +01:00
John Ericson 22b278e011 Automatically document builtin constants
This is done in roughly the same way builtin functions are documented.

Also auto-link experimental features for primops, subsuming PR #8371.

Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-06-27 09:37:54 -04:00
Valentin Gagarin f8620758aa display documentation on manifest files separately
it's probably better not to show the manifest file documentation in the
command-specific pages, because these are implementation details that are not really practically useful.

this means no additional hassle for building the manual, but clutters
the table of contents a bit.
2023-04-28 12:10:36 +02:00
Alexander Bantyev 8a93b5a551 Document user files of nix 2023-04-26 15:38:19 +02:00
John Ericson 73eb6a2a57 Single page for experimental feature descriptions
As requested by @fricklerhandwerk.
2023-04-09 11:01:23 -04:00
John Ericson bc192a95ef Describe active experimental features in the contributing guide
They are put in the manual separate pages under the new overarching
description of experimental features.

The settings page just lists the valid experimental feature names (so
people know what a valid setting entry looks like), with links to those
pages. It doesn't attempt to describe each experimental feature as that
is too much information for the configuration settings section.
2023-04-06 18:07:59 -04:00
John Ericson 53d0836347 Assemble experimental feature docs outside of Nix itself
Instead of constructing a markdown list in C++ (which involved all sorts
of nasty string literals), export some JSON and assemble it with the
manual build system.

Besides following the precedent set with other dumped data, this is a
better separate of content and presentation; if we decide for example we
want to display this information in a different way, or in a different
section of the manual, it will become much easier to do so.
2023-04-04 22:57:11 -04:00
Valentin Gagarin cde78f9417 process includes first
otherwise the order of found `.md` files will influence if `@docroot@`
is replaced before them being included, which may mess up relative
links.

the weirdest thing about it is that the mess-up happens
deterministically on macOS, but deterministically doesn't happen on
Linux!
2023-03-30 13:55:44 +02:00
Alexander Bantyev 36b059748d Split nix-env and nix-store documentation per-subcommand
Documentation on "classic" commands with many sub-commands are
notoriously hard to discover due to lack of overview and anchor links.
Additionally the information on common options and environment variables
is not accessible offline in man pages, and therefore often overlooked
by readers.

With this change, each sub-command of nix-store and nix-env gets its
own page in the manual (listed in the table of contents), and each own
man page.

Also, man pages for each subcommand now (again) list common options
and environment variables. While this makes each page quite long and
some common parameters don't apply, this should still make it easier
to navigate as that additional information was not accessible on the
command line at all.

It is now possible to run 'nix-store --<subcommand> --help` to display
help pages for the given subcommand.

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-03-30 09:46:28 +02:00
Alexander Bantyev 84c2c09ec2 Manual: fail when #include-d file does not exist 2023-03-30 09:41:46 +02:00
Eelco Dolstra 2851e239a7 Make useAnchors a named argument 2023-03-23 10:08:49 +01:00
Eelco Dolstra 8d6d59cb1b nix store --help: Include store type documentation 2023-03-21 14:03:40 +01:00
John Ericson 6910f5dcb6 Generate API docs with Doxygen
The motivation is as stated in issue #7814: even though the the C++ API
is internal and unstable, people still want it to be well documented for
sake of learning, code review, and other purposes that aren't predicated
on it being stable.

Fixes #7814

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2023-03-10 12:51:06 -05:00
Valentin Gagarin e065131c1b
cosmetic indentation
Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
2023-03-03 12:56:23 +01:00
Alexander Bantyev dd0aab2f94
Documentation: process #include directives 2023-03-01 14:01:45 +04:00
Alexander Bantyev 21fb1a5ec2
doc/manual/local.mk: Use tabs instead of spaces everywhere 2023-03-01 14:01:23 +04:00
Robert Hensing 1a86d3e98e local.mk: Don't log docroot comments
These were accidentally logged and do not need to appear in make's
log output.
2023-02-07 23:34:36 +01:00
Robert Hensing da4d4feacf doc/manual/hacking: Document @docroot@ variable 2023-01-10 22:30:41 +01:00
Robert Hensing fd2af69e60 doc/manual: Move the html files back where they were before
... before the link checking "output" was added, bumping the
html output into a subdirectory.
2023-01-10 22:30:41 +01:00
Robert Hensing 34a1e0d29b doc/manual: Introduce @docroot@ as a stable base for includable snippets
This way the links are clearly within the manual (ie not absolute paths),
while allowing snippets to reference the documentation root reliably,
regardless of at which base url they're included.
2023-01-10 22:30:41 +01:00
Robert Hensing be10c09d23 manual: Check links
mdbook-linkcheck is not consistent about its warning setting.
It disables some warnings, but not the warnings about lack of
fragment checking support; hence the extra filtering.
2023-01-10 22:30:41 +01:00
Valentin Gagarin ebeaf03558 do not render links in man pages
this is a follow-up on e7dcacb.

most links are relative and this should not be too much of a detriment.
2022-12-07 16:20:25 +01:00
Ana Hobden 069409d167 Print common flags in --help 2022-10-07 09:07:22 -07:00
Valentin Gagarin e7dcacbd7c do not render relative links in help pages
this simplifies the setup a lot, and avoids weird looking `./file.md`
links showing up.

it also does not show regular URLs any more. currently the command
reference only has few of them, and not showing them in the offline
documentation is hopefully not a big deal.

instead of building more special-case solutions, clumsily preprocessing
the input, or issuing verbal rules on dealing with URLs, should better
be solved sustainably by not rendering relative links in `lowdown`:

https://github.com/kristapsdz/lowdown/issues/105
2022-08-26 17:10:41 +02:00
John Ericson bc118854d0 Merge remote-tracking branch 'upstream/master' into doc-what-is-nix 2022-08-04 09:11:42 -04:00
John Ericson 523359d133 WIP: Document the design of Nix
The current docs are all "how to do things" and no "what is Nix" or "why
are things the way they are".

I see lots of misconception on the wider internet, and I also think we
would benefit from a "living document" to answer some questions people
currently turn to the thesis for.

I think a new section of the manual can address all these issues.
2022-08-04 12:37:46 +02:00
Valentin Gagarin 499ed26508 manual: remove "Writing Nix Expressions" chapter
it is out of date, all over the place in level of detail, is really
about `nixpkgs`, and in general instructions should not be part of
a reference manual.

also:
- update redirects and internal links
- use "Nix language" consistently
2022-08-04 11:59:25 +02:00
Jan Tojnar 3272afa17b doc: Port anchors preprocessor to jq script
Python is only pulled into the build closure by Mercurial, which might end up being removed.
Let’s port the script to jq, which is more likely to stay.
2022-05-26 18:17:21 +02:00
Jan Tojnar 4de84e095d doc: Introduce pre-processor for adding anchors to text
It is now possible to use the following syntax to insert anchors into the text:

    []{#anchor-name}

The anchor will allow linking to the location it is placed by appending #anchor-name to the URL.

Additionally, it is possible to create a link pointing to its own location by adding text between the square brackets:

    [`--add-root`]{#opt-add-root}
2022-05-26 17:54:15 +02:00
Guillaume Desforges 2cc645a91a Add html make target 2022-02-23 15:06:13 +01:00
Tom Bereknyei 152e3cda0c reproducibility: determinstic man page output for cores 2021-11-26 10:55:43 -05:00
Eelco Dolstra 08aa7daee0 Remove links to .md files in help output
Fixes #5337.
2021-10-06 13:01:18 +02:00
Eelco Dolstra 8fdb1d057a Quiet 2021-09-22 14:12:31 +02:00
Eelco Dolstra 49a932fb18 nix --help: Display help using lowdown instead of man
Fixes #4476.
Fixes #5231.
2021-09-13 14:45:21 +02:00
Eelco Dolstra ff03fb6743 Manual: Depend on all *.md files 2021-09-09 15:01:19 +02:00
Sergei Trofimovich 33fa5f3cd9 doc/manual/local.mk: fix 'make install DESTDIR=...'
Install failure is observed when we try to install
into inplace location as non-root:

```
$ LANG=C make install DESTDIR=$PWD/__i__ V=1
RUST_LOG=warn mdbook build doc/manual -d /usr/share/doc/nix/manual
2021-08-28 13:29:58 [ERROR] (mdbook::utils): Error: Rendering failed
2021-08-28 13:29:58 [ERROR] (mdbook::utils):    Caused By: Unexpected error when constructing destination path
2021-08-28 13:29:58 [ERROR] (mdbook::utils):    Caused By: Permission denied (os error 13)
make: *** [doc/manual/local.mk:98: /usr/share/doc/nix/manual/index.html] Error 101
```

The change is to prefix paths with `$(DESTDIR)`.
2021-08-28 13:31:34 +01:00
Eelco Dolstra d64f9671fc
Merge pull request #5094 from Pamplemousse/simpler_doc
doc/manual: don't need to copy `highlight.js` manually
2021-08-05 15:13:07 +02:00
Pamplemousse de39cfb9f3 doc/manual: don't need to copy highlight.js manually
Signed-off-by: Pamplemousse <xav.maso@gmail.com>
2021-08-04 19:47:05 -07:00
regnat 441be5d59a Remove dead code in doc’s local.mk 2021-07-27 14:37:55 +02:00