Merge pull request #981 from phaer/docs

mkdocs-based documentation site
This commit is contained in:
Paul Haerle 2024-06-26 19:09:32 +02:00 committed by GitHub
commit 06027e2e42
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
74 changed files with 804 additions and 280 deletions

4
.gitignore vendored
View File

@ -5,4 +5,6 @@
result
interpreter
__pycache__
*.egg-info
*.egg-info
# symlink for devshell
docs/src/reference

View File

@ -13,7 +13,9 @@
<a href="https://github.com/nix-community/dream2nix/tree/main/examples/packages">Example Packages</a>
</p>
!!! Warning: dream2nix is unstable software. While simple UX is one of our main focus points, the APIs are still under development. Do expect changes that will break your setup.
!!! warning
dream2nix is unstable software. While simple UX is one of our main focus points, the APIs are still under development. Do expect changes that will break your setup.
### legacy dream2nix

67
docs/README.md Normal file
View File

@ -0,0 +1,67 @@
# About this Documentation
Dream2nix documentation is generated from markdown via
[mkdocs](https://www.mkdocs.org/) and [mkdocs-material](https://squidfunk.github.io/mkdocs-material/).
## Build
You can build and server it locally with, i.e.:
``` shellsession
nix build .#website
python3 -m http.server -d ./result
```
# Development shell
Or alternatively run a development environment with:
``` shellsession
nix develop .#website
```
Upon entering the devshell, it will change into
`./docs` and symlink a build of the [options reference](#options-reference)
into `./docs/src/reference`.
Normal builds will always use an up-to-date options reference,
but during development you need to update this symlink yourself
and remove it after use.
i.e. from inside the shell in `./docs`:
``` shellsession
# update
ln -sfT $(nix build --print-out-paths --no-link ..#optionsReference) ./src/reference
# remove
rm ./src/reference
```
## Options Reference
The reference documentation for [modules](./modules.md) is auto-generated via
a custom hook in `docs/hooks/render_options.py` and a derivation in
`.#optionsReference`.
The derivation includes, for each module, an `options.json` file as generated by nix via `pkgs.nixosOptionsDoc` as well as a `README.md` file, copied from the modules source directory. The existence of such a `README.md` is used as an indicator on whether to include a module in the reference documentation.
The hook runs whenever mkdocs renders one of the `README.md`s. Each of them gets concatenated with header and options reference, after the latter are run through jinja templates in `./docs/theme`.
## Notes on Markdown
Mkdocs uses a markdown dialect from [Python-Markdown](https://python-markdown.github.io/) with various, optional extensions listed in `./docs/mkdocs.yml`.
This is different from the CommonMark dialect, as implemented by [markdown-it-py](https://pypi.org/project/markdown-it-py/) and used in NixOS official documentation.
The differences between both don't seem to be too relevant for the markdown features used in our [options reference](#options-reference), but it's good
to be aware of them when writing longer prose.
[mkdocs-materials reference](https://squidfunk.github.io/mkdocs-material/reference) provides a
good overview on useful extensions.
## CI
The documentation is published on GitHub pages via a GitHub action, defined in [.github/workflows/pages.yml](https://github.com/nix-community/dream2nix/blob/main/.github/workflows/pages.yml)

View File

@ -0,0 +1,122 @@
import logging
import json
from pathlib import Path
from collections import OrderedDict
from typing import Dict, Tuple
from urllib.request import UnknownHandler
from mkdocs.structure.pages import Page
from mkdocs.structure.nav import Navigation, Section
from mkdocs.structure.files import Files
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.plugins import event_priority
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter
log = logging.getLogger("mkdocs")
def is_reference_page(page: Page) -> bool:
return page.file.src_path.startswith("reference/")
def pygments(code: str, lang: str) -> str:
return highlight(code, get_lexer_by_name(lang), HtmlFormatter())
def sort_options(item: Tuple[str, Dict], module_name: str) -> int:
"""
Sort the modules. First the one the page is about,
then single options, then the rest, alphabetically
"""
name, option = item
if name == module_name:
return -1
elif len(option["children"]) == 0:
return 0
else:
return ord(name[0])
def preprocess_options(options, module_name):
tree = dict()
for name, option in options.items():
if name.startswith("_module"):
continue
cursor = tree
parts = name.split(".")
for index, part in enumerate(parts):
if part not in cursor:
if index + 1 == len(parts):
cursor[part] = dict(**option, children={})
else:
cursor[part] = dict(children=dict())
cursor = cursor[part]
else:
cursor = cursor[part]["children"]
return OrderedDict(sorted(tree.items(), key=lambda i: sort_options(i, module_name)))
def on_page_markdown(
markdown: str, page: Page, config: MkDocsConfig, files: Files
) -> str | None:
"""Check whether the source path starts with "reference/".
If it does:
- render a header template, containing values from the source markdown file
- render the source markdown file
- render an options.json file containing nixos option definitions from the
same directory where the source file is found. Then render those options.
"""
if not is_reference_page(page):
return markdown
src_path = Path(config.docs_dir) / page.file.src_path
module_name = src_path.parent.stem
env = config.theme.get_env()
env.filters["pygments"] = pygments
header = env.get_template("reference_header.html").render(meta=page.meta)
options_path = src_path.parent / "options.json"
if not options_path.exists():
log.error(f"{options_path} does not exist")
return None
with open(options_path, "r") as f:
options = preprocess_options(json.load(f), module_name)
reference = env.get_template("reference_options.html").render(options=options)
return "\n\n".join([header, markdown, reference])
@event_priority(-100)
def on_nav(nav: Navigation, config: MkDocsConfig, files: Files) -> Navigation | None:
"""Customize the navigation: If a reference section is found,
filter for a "state" variable defined in a markdown files front-matter.
Leave all items where "state" equals "released" as-is, but put
all others in an "experimental" section below that."""
try:
reference_section = next(filter(lambda i: i.title == "Reference", nav.items))
reference_index = nav.items.index(reference_section)
except StopIteration:
# Return the navigation as-is if we don't find
# a reference section
return nav
released = []
experimental = []
for page in reference_section.children:
# to have metadata from the yaml front-matter available
page.read_source(config)
state = page.meta.get("state")
if state == "released":
released.append(page)
else:
experimental.append(page)
experimental_section = Section("Experimental Modules", experimental)
reference_section.children = released + [experimental_section]
nav.items[reference_index] = reference_section
return nav

65
docs/mkdocs.yml Normal file
View File

@ -0,0 +1,65 @@
site_name: Dream2Nix
docs_dir: "src"
site_url: "https://nix-community.github.io/dream2nix"
site_dir: !ENV out
repo_url: https://github.com/nix-community/dream2nix
repo_name: nix-community/dream2nix
edit_uri: edit/main/docs/src/
plugins:
- search
- awesome-pages
hooks:
- hooks/render_options.py
extra_css:
- style.css
markdown_extensions:
- toc:
permalink: true
- tables
- admonition
- pymdownx.escapeall
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.tasklist
- pymdownx.details
validation:
omitted_files: warn
absolute_links: warn
unrecognized_links: warn
theme:
custom_dir: theme
name: material
favicon: favicon.png
logo: favicon.png
features:
- search.suggest
- search.highlight
- instant
- navigation.instant
- navigation.instant.prefetch
- navigation.instant.progress
- navigation.tracking
- navigation.path
- navigation.top
- toc.follow
- content.code.copy
- content.code.annotate
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/nix-community/dream2nix
name: Dream2nix on Github
- icon: fontawesome/solid/comments
link: https://matrix.to/#/#dream2nix:nixos.org
name: Dream2nix Matrix Channel

15
docs/src/.pages Normal file
View File

@ -0,0 +1,15 @@
nav:
- "Home": index.md
- "Getting Started": gettingstarted.md
- Concepts:
- "Modules": modules.md
- "Overriding Dependencies": overrides.md
- Reference: reference
- Examples:
- "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
- "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
- "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
- Documentation: docs.md
- Notes:
- "v1 API design docs": v1-api
- development-roundups

1
docs/src/docs.md Symbolic link
View File

@ -0,0 +1 @@
../README.md

BIN
docs/src/favicon.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.7 KiB

View File

@ -1,5 +1,3 @@
## Getting started
To package a piece of software with dream2nix, you'd typically start with
a bare-bones dream2nix flake like this:
@ -60,8 +58,8 @@ And a `default.nix` that looks like this:
```
To find out which dream2nix modules to import, browse through the modules
on the left and the [examples](./examples.md). When getting started, the
'/packages/languages' collection will be most helpful.
on the left and the [examples](https://github.com/nix-community/dream2nix/tree/main/examples/packages). When getting started, the
`./packages/languages` collection will be most helpful.
Once you have imported a module, this module will make ecosystem-dependent
functions available to create your package definition, such as `mkDerivation`

View File

@ -6,9 +6,9 @@ For some more background information, check out the initial exploration of this
@edolstra 's [talk about this topic](https://www.youtube.com/watch?v=dTd499Y31ig) is also worth watching.
# Benefits
## Benefits
## Deprecate override functions
### Deprecate override functions
Changing options of packages in nixpkgs can require chaining different override functions like this:
@ -39,7 +39,7 @@ Changing options of packages in nixpkgs can require chaining different override
See htop module definition [here](https://github.com/nix-community/dream2nix/blob/main/examples/packages/basics/htop-with-flags/default.nix).
## Type safety
### Type safety
The following code in nixpkgs mkDerivation mysteriously skips the patches:
@ -56,7 +56,7 @@ mkDerivation {
A definition for option `[...].dontPatch' is not of type `boolean' [...]
```
## Catch typos
### Catch typos
The following code in nixpkgs mkDerivation builds **without** openssl_3.
@ -73,7 +73,7 @@ mkDerivation {
The option `[...].nativBuildInputs' does not exist
```
## Environment variables clearly defined
### Environment variables clearly defined
`dream2nix` requires a clear distinction between known parameters and user-defined variables.
Defining `SOME_VARIABLE` at the top-level, would raise:
@ -93,7 +93,7 @@ Instead it has to be defined under `env.`:
}
```
## Documentation / Discoverability
### Documentation / Discoverability
No more digging the source code to find possible options to override.
@ -101,11 +101,11 @@ Documentation similar to [search.nixos.org](https://search.nixos.org) can be gen
Every package built with `dream2nix` has a `.docs` attribute that builds an html documentation describing it's options.
## Package blueprints
### Package blueprints
With `dream2nix`, packages don't need to be fully declared. Options can be left without defaults, requiring the consumer to complete the definition.
## Flexibility
### Flexibility
The nixos module system gives maintainers more freedom over how packages are split into modules. Separation of concerns can be implemented more easily.
For example, the dependency tree of a package set can be factored out into a separate module, allowing for simpler modification.

12
docs/src/style.css Normal file
View File

@ -0,0 +1,12 @@
.md-header .md-logo {
background-color: white;
border-radius: 100%;
}
[data-md-component="toc"] .md-nav__link {
display: inline-flex;
}
.md-typeset td pre {
margin: 0;
}

3
docs/src/v1-api/.pages Normal file
View File

@ -0,0 +1,3 @@
nav:
- summary.md
- ...

56
docs/theme/partials/toc-item.html vendored Normal file
View File

@ -0,0 +1,56 @@
<!--
Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
-->
<!-- Table of contents item -->
<li class="md-nav__item">
{%- set should_collapse = toc_item.level > 2 and toc_item.children -%}
{% if should_collapse -%}
<details>
<summary>
{%- endif %}
<a href="{{ toc_item.url }}" class="md-nav__link">
<span class="md-ellipsis">
{%- if page.url.split("/")[-3] == "reference" -%}
{{ toc_item.title.split(".")[-1] }}
{%- else -%}
{{ toc_item.title }}
{%- endif -%}
</span>
</a>
{% if should_collapse -%}
</summary>
{%- endif %}
<!-- Table of contents list -->
{% if toc_item.children %}
<nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
<ul class="md-nav__list">
{% for toc_item in toc_item.children %}
{% include "partials/toc-item.html" %}
{% endfor %}
</ul>
</nav>
{% endif %}
{% if should_collapse -%}
</details>
{%- endif %}
</li>

18
docs/theme/reference_header.html vendored Normal file
View File

@ -0,0 +1,18 @@
<table style="float: right;">
<tr>
<td>state:</td>
<td>{{ meta.state | default("experimental") }}</td>
</tr>
<tr>
<td>maintainers:</td>
<td>
{% if meta.maintainers -%}
{% for m in meta.maintainers -%}<a href="https://github.com/{{m}}">@{{m}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}
{%- else -%}
noone, maybe <strong>you</strong>?
{% endif %}
</td>
</tr>
</table>
## Introduction

40
docs/theme/reference_options.html vendored Normal file
View File

@ -0,0 +1,40 @@
## Options
{%- for name, option in options.items() recursive %}
##{{loop.depth * "#"}} {{ ((option.loc | join (".")) or name).replace("<", "&lt;").replace(">", "&gt;") }}
{% if (option.description or '') != "This option has no description." -%}
{{ option.description or '' }}
{%- endif %}
{% if "type" in option %}
<table>
<tr>
<td>type</td>
<td>{{ option.type}} {{ "(read only)" if option.readOnly else "" }}</td>
</tr>
<tr>
<td>source</td>
<td>{%- for d in option.declarations -%}<a href="{{d.url}}">{{d.name}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}</td>
</tr>
{%- if option.default -%}
<tr>
<td>default</td>
<td>{{(option.default | default({})).text | pygments("nix")}}</td>
</tr>
{%- endif -%}
{%- if option.example -%}
<tr>
<td>example</td>
<td>
{{(option.example | default({})).text | pygments("nix")}}
</td>
</tr>
{%- endif -%}
</table>
{% endif %}
{%- if option.children -%}
{{ loop(option.children.items()) }}
{%- endif %}
{%- endfor %}

View File

@ -9,7 +9,7 @@
];
name = "hello";
version = "2.12";
version = "2.12.1";
deps = {nixpkgs, ...}: {
inherit
@ -21,7 +21,7 @@
mkDerivation = {
src = builtins.fetchTarball {
url = "https://ftp.gnu.org/gnu/hello/hello-${config.version}.tar.gz";
sha256 = "sha256-4GQeKLIxoWfYiOraJub5RsHNVQBr2H+3bfPP22PegdU=";
sha256 = "0xw6cr5jgi1ir13q6apvrivwmmpr5j8vbymp0x6ll0kcv6366hnn";
};
};
}

View File

@ -1,3 +1,10 @@
---
title: "groups"
state: experimental
maintainers:
- DavHau
---
Module to deal with package sets (so called groups in dream2nix)
## Separate different kinds of dependencies

View File

@ -0,0 +1,6 @@
---
title: "haskell-cabal"
state: "experimental"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-builder-v3"
state: "experimental"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "python-pdm"
state: "experimental"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "python-pyproject"
state: "experimental"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "spago"
state: "experimental"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "buildPythonPackage"
state: "released"
maintainers:
- DavHau
---

View File

@ -93,13 +93,15 @@ in {
description = ''
Whether the pyproject format should be used. When set to `true`,
`pypaBuildHook` will be used, and you can add the required build dependencies
from `build-system.requires` to `build-system`. Note that the pyproject
format falls back to using `setuptools`, so you can use `pyproject = true`
even if the package only has a `setup.py`. When set to `false`, you can
use the existing hooks or provide your own logic to build the
package. This can be useful for packages that don't support the pyproject
format. When unset, the legacy `setuptools` hooks are used for backwards
compatibility.
from `build-system.requires` to `build-system`.
Note that the pyproject format falls back to using `setuptools`, so
you can use `pyproject = true` even if the package only has a `setup.py`.
When set to `false`, you can use the existing hooks or provide your own
logic to build the package. This can be useful for packages that don't
support the pyproject format.
When unset, the legacy `setuptools` hooks are used for backwards compatibility.
'';
};

View File

@ -0,0 +1,6 @@
---
title: "buildRustPackage"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "builtins-derivation"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "core"
state: "released"
maintainers:
- DavHau
---

View File

@ -1 +1,8 @@
---
title: "mkDerivation"
state: released
maintainers:
- DavHau
---
A package module based on the mkDerivation builder from nixpkgs

View File

@ -0,0 +1,6 @@
---
title: "multi-derivation-package"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nixpkgs-overrides"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-devshell-v3"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-devshell"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-granular-v3"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-granular"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-node-modules-v3"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-node-modules"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-package-json-v3"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-package-json"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-package-lock-v3"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "nodejs-package-lock"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "overrides"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "package-func"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "php-composer-lock"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "php-granular"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,30 @@
---
title: "pip"
state: released
maintainers:
- phaer
---
A module to package python projects via [pip](https://pip.pypa.io/).
Under the hood, it uses [./pkgs/fetchPipMetadata](https://github.com/nix-community/dream2nix/tree/main/pkgs/fetchPipMetadata) to
run `pip install --dry-run --report [...]` with reproducible inputs and converts the resulting installation report into a dream2nix
lock file.
!!! note
Due to limitations in `pip`s cross-platform support, the resulting
lock-files are platform-specific!
We therefore recommend setting `paths.lockFile` to `lock.${system}.json`
for all projects where you use the pip module.
Check out the [pdm module](../WIP-python-pdm/index.md) if you need a solution that
allows locking for multiple platforms at once!
During building, it uses this lock file to build each dependency as well as the top-level package in separate derivations
while allowing overrides and further customization via [dream2nix module system](../../modules.md).
## Getting started
See [Build a python project with pip](../../guides/pip.md).

View File

@ -0,0 +1,6 @@
---
title: "rust-cargo-lock"
state: "released"
maintainers:
- DavHau
---

View File

@ -0,0 +1,6 @@
---
title: "rust-crane"
state: "released"
maintainers:
- DavHau
---

View File

@ -9,39 +9,33 @@
system,
...
}: let
modules' = self.modules.dream2nix;
modules = lib.filterAttrs (name: _: ! lib.elem name excludes) modules';
dream2nixRoot = ../../../.;
dream2nix = import dream2nixRoot;
excludes = [
# NOT WORKING
# TODO: fix those
"core"
"ui"
"docs"
"assertions"
"nixpkgs-overrides"
# doesn't need to be rendered
"_template"
];
public = lib.genAttrs [
"nodejs-granular-v3"
"nodejs-package-lock-v3"
"php-composer-lock"
"php-granular"
"pip"
"rust-cargo-lock"
"rust-crane"
] (name: null);
# interface
sourcePathStr = toString dream2nix;
baseUrl = "https://github.com/nix-community/dream2nix/blob/master";
specialArgs = {
inherit dream2nix;
packageSets.nixpkgs = pkgs;
getOptions = {modules}: let
options = lib.flip lib.mapAttrs modules (
name: module: let
evaluated = lib.evalModules {
specialArgs = {
inherit dream2nix;
packageSets.nixpkgs = pkgs;
};
modules = [module];
};
in
evaluated.options
);
docs = lib.flip lib.mapAttrs options (name: options:
pkgs.nixosOptionsDoc {
inherit options;
inherit transformOptions;
warningsAreErrors = false;
});
in {
inherit options docs;
};
transformOptions = opt:
opt
// {
@ -49,7 +43,7 @@
map
(
decl: let
subpath = lib.removePrefix sourcePathStr (toString decl);
subpath = lib.removePrefix (toString dream2nix) (toString decl);
in {
url = baseUrl + subpath;
name = "dream2nix" + subpath;
@ -57,144 +51,106 @@
)
opt.declarations;
};
# 0 = no chapters, 1 = one level of chapters, 2 = two levels of chapters ...
chaptersNesting = 1;
# A tree where nodes are (sub)chapters and leafs are options.
# Nesting can be arbitrary
chaptersTree = {
"Modules" =
lib.filterAttrs (name: _: public ? ${name}) optionsTree;
"Modules (Internal + Experimental)" =
lib.filterAttrs (name: _: ! public ? ${name}) optionsTree;
};
optionsTree = lib.flip lib.mapAttrs modules (
name: module: let
evaluated = lib.evalModules {
inherit specialArgs;
modules = [module];
};
in
# lib.trace "Rendering Module ${name}"
(builtins.removeAttrs evaluated.options ["_module"])
);
# implementation
highlight-js = let
highlight-core = pkgs.fetchurl {
url = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js";
hash = "sha256-g3pvpbDHNrUrveKythkPMF2j/J7UFoHbUyFQcFe1yEY=";
};
highlight-nix = pkgs.fetchurl {
url = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/nix.min.js";
hash = "sha256-BLoZ+/OroDAxMsdZ4GFZtQfsg6ZJeLVNeBzN/82dYgk=";
};
in
pkgs.runCommand "highlight-js" {} ''
cat ${highlight-core} > $out
cat ${highlight-nix} >> $out
modules =
lib.filterAttrs (
name: _:
! lib.elem name
[
# NOT WORKING
# TODO: fix those
"core"
"ui"
"docs"
"assertions"
"nixpkgs-overrides"
# doesn't need to be rendered
"_template"
]
)
dream2nix.modules.dream2nix;
options = getOptions {
inherit modules;
};
optionsReference = let
publicModules =
lib.filterAttrs
(n: v: lib.pathExists (v + "/README.md"))
modules;
createReference = name: sourcePath: ''
target_dir="$out/${name}/"
mkdir -p "$target_dir"
ln -s ${sourcePath}/README.md "$target_dir/index.md"
ln -s ${options.docs.${name}.optionsJSON}/share/doc/nixos/options.json "$target_dir"
cat > "$target_dir/.pages" <<EOF
collapse_single_pages: true
nav:
- ...
EOF
'';
highlight-style = pkgs.fetchurl {
url = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/vs.min.css";
hash = "sha256-E1kfafj5iO+Tw/04hxdSG+OnvczojOXK2K0iCEYfzSw=";
};
optionsToMdFile = options: let
docs = pkgs.nixosOptionsDoc {
inherit options;
inherit transformOptions;
warningsAreErrors = false;
};
in
docs.optionsCommonMark;
mdFiles = nesting: chapters:
if nesting == 0
then lib.mapAttrs (name: optionsToMdFile) chapters
else lib.concatMapAttrs (name: mdFiles (nesting - 1)) chapters;
mdFilesDir = pkgs.runCommand "md-files-dir" {} ''
mkdir -p $out
cp -r ${lib.concatStringsSep "\n cp -r " (lib.mapAttrsToList (name: file: "${file} $out/${name}.md") (mdFiles chaptersNesting chaptersTree))}
'';
spacing = depth:
if depth == 0
then "- "
else " " + spacing (depth - 1);
# returns "" for chapters with nesting or an md file for chapters with options
chapterUrl = nesting: name:
if nesting == 0
then "options/${name}.md"
else "";
renderChapters = depth: nesting: chapters:
lib.concatStringsSep "\n"
(lib.flip lib.mapAttrsToList chapters (
name: chapter:
"${spacing depth}[${name}](${chapterUrl nesting name})"
+ lib.optionalString (nesting > 0) (renderChapters (depth + 1) (nesting - 1) chapter)
));
summaryMdFile =
pkgs.writeText "summary.md"
(renderChapters 0 chaptersNesting chaptersTree);
mdBookSource = pkgs.runCommand "website-src" {} ''
mkdir -p $out/options
cp ${summaryMdFile} $out/SUMMARY.md
cp -r ${mdFilesDir}/* $out/options/
# add table of contents for each md file
for file in $out/options/*.md; do
name="$(basename "$file")"
name="''${name%.md}"
echo "# $name - options" > "$file.tmp"
echo '<!-- toc -->' | cat - "$file" >> "$file.tmp"
mv $file.tmp $file
done
'';
pkgs.runCommand "reference" {
} ''
${lib.concatStringsSep "\n" (lib.attrValues (lib.mapAttrs createReference publicModules))}
'';
website =
pkgs.runCommand "website" {
nativeBuildInputs = [
pkgs.mdbook
pkgs.mdbook-linkcheck
# This inserts a table of contents at each '<!-- toc -->'
inputs.mdbook-toc.defaultPackage.${system}
pkgs.python3.pkgs.mkdocs
pkgs.python3.pkgs.mkdocs-material
self.packages.${system}.mkdocs-awesome-pages-plugin
optionsReference
];
} ''
cp -rL --no-preserve=mode ${dream2nixRoot}/website/* ./
cp -r ${mdBookSource}/* src/
# insert highlight.js
cp ${highlight-js} ./src/highlight.js
cp ${highlight-style} ./src/highlight.css
# merge original and generated SUMMARY.md
cp ${dream2nixRoot}/website/src/SUMMARY.md SUMMARY.md.orig
{
while read ln; do
case "$ln" in
"# Modules Reference")
echo "# Modules Reference"
cat ${mdBookSource}/SUMMARY.md
;;
*)
echo "$ln"
;;
esac
done
} < SUMMARY.md.orig > src/SUMMARY.md
# insert icon
mkdir -p ./theme
cp ${../../../modules/dream2nix/core/docs/theme/favicon.png} ./theme/favicon.png
${pkgs.mdbook}/bin/mdbook build --dest-dir out
mv out/html $out
cp -rL --no-preserve=mode ${dream2nixRoot}/docs/* .
ln -sfT ${optionsReference} ./src/reference
mkdocs build
'';
in {
packages.mkdocs-awesome-pages-plugin = pkgs.callPackage ./mkdocs-awesome-pages-plugin.nix {
inherit
(pkgs.python3.pkgs)
buildPythonPackage
mkdocs
wcmatch
natsort
beautifulsoup4
mock-open
importlib-metadata
poetry-core
pytestCheckHook
pythonOlder
;
};
packages.optionsReference = optionsReference;
packages.website = website;
packages.docs-generated-mdbook-src = mdBookSource;
devShells.website = let
pythonWithDeps = pkgs.python3.withPackages (
ps: [
ps.ipython
ps.black
ps.pytest
ps.pytest-cov
]
);
in
pkgs.mkShell {
inputsFrom = [self.packages.${system}.website];
packages = [
pythonWithDeps
];
shellHook = ''
cd $PRJ_ROOT/docs
if [ ! -d src/reference ]; then
echo "linking .#reference to src/reference, you need to update this manually\
and remove it before a production build"
ln -sfT $(nix build ..#reference --no-link --print-out-paths) src/reference
fi
'';
};
};
}

View File

@ -0,0 +1,59 @@
# Can be removed from dream2nix repo when
# https://github.com/NixOS/nixpkgs/pull/320709
# is in nixpkgs-unstable
{
lib,
buildPythonPackage,
fetchFromGitHub,
poetry-core,
mkdocs,
wcmatch,
natsort,
pytestCheckHook,
beautifulsoup4,
mock-open,
importlib-metadata,
pythonOlder,
}:
buildPythonPackage rec {
pname = "mkdocs-awesome-pages-plugin";
version = "2.9.2";
pyproject = true;
disabled = pythonOlder "3.9";
src = fetchFromGitHub {
owner = "lukasgeiter";
repo = "mkdocs-awesome-pages-plugin";
rev = "refs/tags/v${version}";
hash = "sha256-pYyZ84eNrslxgLSBr3teQqmV7hA+LHwJ+Z99QgPdh6U=";
};
propagatedBuildInputs = [
mkdocs
wcmatch
natsort
];
nativeBuildInputs = [poetry-core];
nativeCheckInputs = [
pytestCheckHook
beautifulsoup4
mock-open
importlib-metadata
];
disabledTestPaths = [
# requires "generatedfiles" mkdocs plugin
"mkdocs_awesome_pages_plugin/tests/e2e/test_gen_files.py"
];
meta = with lib; {
description = "An MkDocs plugin that simplifies configuring page titles and their order";
homepage = "https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin";
changelog = "https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/blob/v${version}/CHANGELOG";
license = licenses.mit;
maintainers = with maintainers; [phaer];
};
}

View File

@ -1,10 +0,0 @@
# Website
This directory contains markdown pages under ./src which are rendered to an html website using the tool mdbook.
The website can be built via:
```shellSession
$ nix build .#website
```
In addition to what's already in ./src, this derivation generates and inserts reference documentation pages. One for each dream2nix module in /modules/dream2nix.

View File

@ -1,23 +0,0 @@
[book]
authors = ["David Hauer", "Various contributors"]
language = "en"
multilingual = false
src = "src"
title = "dream2nix"
[output.html]
git-repository-url = "https://github.com/nix-community/dream2nix"
edit-url-template = "https://github.com/nix-community/dream2nix/edit/main/modules/dream2nix/{path}"
no-section-label = true
additional-css = [ "style.css" ]
additional-js = [ "no-edit-options.js" ]
[output.html.print]
enable = false # big single page; don't need that
[output.linkcheck]
follow-web-links = false # no Internet during the build
[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

View File

@ -1,7 +0,0 @@
if (window.location.pathname.match(/options/)) {
var buttons = document.querySelector("#menu-bar > div.right-buttons")
if (buttons != null) {
buttons.style.display = "none"
}
}

View File

@ -1,17 +0,0 @@
- [Introduction](./intro.md)
- [Getting started](./gettingstarted.md)
- [Contact](./contact.md)
# Examples
- [Examples](./examples.md)
# Concepts
- [Modules](./modules.md)
- [Overriding Dependencies](./overrides.md)
# Modules Reference
# Development Roundups
- [April - June 2022](./development-roundups/2022-april-june.md)
- [July - September 2022](./development-roundups/2022-july-september.md)

View File

@ -1,2 +0,0 @@
If you run into any problems or would like to discuss the project,
check out the [#dream2nix:nixos.org](https://matrix.to/#/#dream2nix:nixos.org) Matrix channel.

View File

@ -1,7 +0,0 @@
# Examples for dream2nix
- [👉 example repository](https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages)
- [👉 example repository using flakes](https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
- [👉 example packages](https://github.com/nix-community/dream2nix/tree/main/examples/packages)
- [👉 basics](https://github.com/nix-community/dream2nix/tree/main/examples/packages/basics)
- [👉 languages](https://github.com/nix-community/dream2nix/tree/main/examples/packages/languages)

View File

@ -1,2 +0,0 @@
This project was funded by [NLnet](https://nlnet.nl/), which is a great way to get your open source project funded. **Applications are still open, you can [apply today](https://nlnet.nl/propose)**.
For more information about dream2nix' funding, please refer to the [funding section of the readme](https://github.com/nix-community/dream2nix#funding)

View File

@ -1 +0,0 @@
!!! Warning: dream2nix is unstable software. While simple UX is one of our main focus points, the APIs are still under development. Do expect changes that will break your setup.

View File

@ -1,31 +0,0 @@
h1.menu-title::before {
content: "";
display: inline-block;
background-image: url(./favicon.png);
background-repeat: no-repeat;
background-size: contain;
width: 1.8ex;
height: 1.8ex;
margin-right: 0.9ex;
vertical-align: middle;
}
.light {
--links: #058;
--sidebar-active: #0af;
}
.sidebar .sidebar-scrollbox {
/* We don't use numbers, so we can take a consistent amount of space */
padding: var(--page-padding) !important;
}
.hljs {
background-color: #f6f7f6;
}
@media (prefers-color-scheme: dark) {
.hljs {
background-color: #1d1f21;
}
}
/* prevents chapters without links to be grey */
.chapter li {
color: #000;
}