1
0
Fork 0

build docs and deploy to github pages

This commit is contained in:
Pierre Penninckx 2023-11-30 10:38:35 -08:00 committed by GitHub
parent 86e86dc787
commit 4a8a7d686c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 272 additions and 30 deletions

69
.github/workflows/pages.yml vendored Normal file
View file

@ -0,0 +1,69 @@
# Inspired from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/.github/workflows/docs.yml
name: Deploy docs
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# TODO: needed ?
# schedule:
# - cron: 0 0 * * 1
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Install nix
uses: cachix/install-nix-action@v20
- name: Build docs
run: |
nix \
--print-build-logs \
--option keep-going true \
--show-trace \
build .#manualHtml
# see https://github.com/actions/deploy-pages/issues/58
cp \
--recursive \
--dereference \
--no-preserve=mode,ownership \
result/share/doc/selfhostblocks \
public
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: ./public
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2

View file

@ -14,4 +14,9 @@ jobs:
with:
name: selfhostblocks
authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
- run: nix flake check -L
- run: |
nix flake \
--print-build-logs \
--option keep-going true \
--show-trace \
check

37
docs/man-pages.xml Normal file
View file

@ -0,0 +1,37 @@
<!-- Copyright (c) 2019-2022, see AUTHORS. Licensed under MIT License, see LICENSE. -->
<reference xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Self Host Blocks Reference Pages</title>
<info>
<author><personname>Self Host Blocks contributors</personname>
</author>
<copyright><year>2022</year><holder>Self Host Blocks contributors</holder>
</copyright>
</info>
<refentry>
<refmeta>
<refentrytitle><filename>selfhostblocks-options</filename></refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="source">Self Host Blocks</refmiscinfo>
</refmeta>
<refnamediv>
<refname><filename>selfhostblocks-options</filename>
</refname><refpurpose>Self Host Blocks configuration specification</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>
This contains the module options available for Self Host Blocks.
</para>
</refsection>
<refsection>
<title>Options</title>
<para>
You can use the following options after importing Self Host Blocks as a flake input, then
importing the default module for your system.
</para>
<xi:include href="./nmd-result/selfhostblocks-options.xml" />
</refsection>
</refentry>
</reference>

71
docs/manual.xml Normal file
View file

@ -0,0 +1,71 @@
<!-- Copyright (c) 2019-2023, see AUTHORS. Licensed under MIT License, see LICENSE. -->
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="book-manual">
<info>
<title>Self Host Blocks manual</title>
</info>
<preface>
<title>Preface</title>
<para>
Complete manual for Self Host Blocks, the building blocks for self-hosting with battery included.
</para>
<para>
If you encounter problems or bugs then please report them on the
<link xlink:href="https://github.com/ibizaman/selfhostblocks/issues">issue tracker</link>.
</para>
</preface>
<appendix xml:id="ch-options">
<title>Self Host Blocks configuration options</title>
<section xml:id="sec-usage">
<title>Usage</title>
<!--
Tags:
<title>
<section xml:id="sec-NAME">
<para>
<filename>
<replaceable>
<varname>
<programlisting language="nix">
-->
<para>
To use these options, import Self Host Blocks as a flake input, then import the default module for your system.
<programlisting language="nix">
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
sops-nix.url = "github:Mic92/sops-nix";
shb.url = "github:ibizaman/selfhostblocks";
shb.inputs.nixpkgs.follows = "nixpkgs";
shb.inputs.sops-nix.follows = "sops-nix";
};
outputs = { self, nixpkgs, shb }: {
nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
shb.nixosModules.x86_64-linux.default
./machine.nix
];
};
};
}
</programlisting>
</para>
</section>
<section xml:id="sec-options">
<title>Options</title>
<xi:include href="./nmd-result/selfhostblocks-options.xml" />
</section>
</appendix>
</book>

View file

@ -81,11 +81,27 @@
"type": "github"
}
},
"nmd": {
"locked": {
"lastModified": 1672240039,
"narHash": "sha256-lmct89fYDOr9YdWVvdJgklv/7WttRSiDAkoi2cvvAW4=",
"owner": "gvolpe",
"repo": "nmd",
"rev": "a59e840c2e8d54415485f349760e1350cb80d911",
"type": "github"
},
"original": {
"owner": "gvolpe",
"repo": "nmd",
"type": "github"
}
},
"root": {
"inputs": {
"flake-utils": "flake-utils",
"nix-flake-tests": "nix-flake-tests",
"nixpkgs": "nixpkgs",
"nmd": "nmd",
"sops-nix": "sops-nix"
}
},

View file

@ -6,15 +6,17 @@
sops-nix.url = "github:Mic92/sops-nix";
nix-flake-tests.url = "github:antifuchs/nix-flake-tests";
flake-utils.url = "github:numtide/flake-utils";
nmd.url = "github:gvolpe/nmd";
};
outputs = { nixpkgs, nix-flake-tests, flake-utils, ... }: flake-utils.lib.eachDefaultSystem (system:
outputs = { nixpkgs, nix-flake-tests, flake-utils, nmd, ... }: flake-utils.lib.eachDefaultSystem (system:
let
pkgs = nixpkgs.legacyPackages.${system};
in
{
nixosModules.default = { config, ... }: {
imports = [
pkgs = import nixpkgs {
inherit system;
overlays = [ nmd.overlays.default ];
};
allModules = [
modules/blocks/authelia.nix
modules/blocks/backup.nix
modules/blocks/davfs.nix
@ -34,8 +36,42 @@
modules/services/nextcloud-server.nix
modules/services/vaultwarden.nix
];
in
{
nixosModules.default = { config, ... }: {
imports = allModules;
};
# Inspiration from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/docs/default.nix#L22
packages.manualHtml = let
setupModule = {
_module.args.pkgs = pkgs.lib.mkForce (pkgs.nmd.scrubDerivations "pkgs" pkgs);
_module.check = false;
};
modulesDocs = pkgs.nmd.buildModulesDocs {
modules = allModules ++ [ setupModule ];
moduleRootPaths = [ ../. ];
mkModuleUrl = path: "https://myproject.foo/${path}";
channelName = "selfhostblocks";
docBook = { id = "selfhostblocks-options"; optionIdPrefix = "shb-opt"; };
};
manual = pkgs.nmd.buildDocBookDocs {
pathName = "SelfHostBlocks";
modulesDocs = [ modulesDocs ];
documentsDirectory = ./docs;
chunkToc = ''
<toc>
<d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-manual">
<?dbhtml filename="index.html"?>
</d:tocentry>
</toc>
'';
};
in
manual.html;
checks =
let
importFiles = files:

View file

@ -14,7 +14,7 @@ in
subdomain = lib.mkOption {
type = lib.types.str;
description = "Subdomain under which Authelia will be served.";
example = "ha";
example = "auth";
};
domain = lib.mkOption {
@ -36,9 +36,17 @@ in
};
autheliaUser = lib.mkOption {
type = lib.types.str;
description = "System user for this Authelia instance";
default = "authelia_" + builtins.replaceStrings ["-" "."] ["_" "_"] fqdn;
type = lib.types.nullOr lib.types.str;
description = ''System user for this Authelia instance.
If set to null, defaults to:
<programlisting language="nix">
"authelia_" +
(builtins.replaceStrings ["-" "."] ["_" "_"]
''${shb.authelia.subdomain}.''${shb.authelia.domain}")
</programlisting>
'';
default = null;
};
secrets = lib.mkOption {
@ -112,7 +120,7 @@ in
services.authelia.instances.${fqdn} = {
enable = true;
user = cfg.autheliaUser;
user = cfg.autheliaUser or "authelia_" + builtins.replaceStrings ["-" "."] ["_" "_"] fqdn;
secrets = {
inherit (cfg.secrets) jwtSecretFile storageEncryptionKeyFile;

View file

@ -6,7 +6,7 @@ in
options.shb.postgresql = {
debug = lib.mkOption {
type = lib.types.bool;
description = lib.mdDocs ''
description = lib.mdDoc ''
Enable debugging options.
Currently enables shared_preload_libraries = "auto_explain, pg_stat_statements"

View file

@ -211,7 +211,7 @@ in
provider = lib.mkOption {
description = lib.mdDoc "VPN provider, if given uses ready-made configuration.";
type = lib.types.nullOf (lib.types.enum [ "nordvpn" ]);
type = lib.types.nullOr (lib.types.enum [ "nordvpn" ]);
default = null;
};