clan/clan-core
12
4
Fork 17
Code Issues 99 Pull Requests 4 Actions 1 Packages Projects 1 Releases Wiki Activity

docs: add reference index pages #1743

Closed
fricklerhandwerk wants to merge 1 commits from fricklerhandwerk/clan-core:rearrange-docs-front into main
pull from: fricklerhandwerk/clan-core:rearrange-docs-front
merge into: clan:main
Conversation 1 Commits 1 Files Changed 10 +182 -267
fricklerhandwerk commented 2024-07-15 09:00:12 +00:00
Collaborator
Copy Link
  • add index pages for each reference documentation category
  • move concepts pages into the reference hierarchy
  • render clanModules overview page in the style of the CLI overview
- add index pages for each reference documentation category - move concepts pages into the reference hierarchy - render clanModules overview page in the style of the CLI overview
fricklerhandwerk added 1 commit 2024-07-15 09:00:12 +00:00
docs: add reference index pages
Some checks failed
buildbot/nix-build .#checks.x86_64-linux.lib-jsonschema-nix-unit-tests Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-docs Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.module-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-inventory-schema-pretty Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-moonlight-sunshine-accept Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-pending-reviews Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-tea-create-pr Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-clan-app Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-zerotier-members Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-webview-ui Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-zt-tcp-relay Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-zerotierone Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.postgresql Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-function-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.nixos-flash-installer Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-module-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.secrets Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.zt-tcp-relay Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.template-minimal Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.wayland-proxy-virtwl Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.syncthing Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.lib-inventory-eval Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.module-clan-vars-eval Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-gui-install-test-ubuntu-22-04 Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.test-backups Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-pytest-with-core Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.flash Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.test-installation Build done.
Details
buildbot/nix-eval Build done.
Details
checks / checks-impure (pull_request) Failing after 3m11s
Details
143355cfcb 
- add index pages for each reference documentation category
- move concepts pages into the reference hierarchy
- render clanModules overview page in the style of the CLI overview
hsjobeki reviewed 2024-07-15 10:18:12 +00:00
docs/site/reference/nix-api/inventory.md
@ -0,0 +1,57 @@
# Inventory
hsjobeki commented 2024-07-15 10:18:12 +00:00
Owner
Copy Link

this file can be generated from suorce, could we remove it first ?

nix build git+https://git.clan.lol/clan/clan-core#inventory-schema-pretty

this file can be generated from suorce, could we remove it first ? `nix build git+https://git.clan.lol/clan/clan-core#inventory-schema-pretty`
hsjobeki reviewed 2024-07-15 11:40:05 +00:00
docs/mkdocs.yml
@ -50,11 +50,10 @@ nav:
- Mesh VPN: getting-started/mesh-vpn.md
- Backup & Restore: getting-started/backups.md
- Flake-parts: getting-started/flake-parts.md
- Concepts:
hsjobeki commented 2024-07-15 11:40:05 +00:00
Owner
Copy Link

I added further explanation to the inventory there.

Maybe the wording is not perfect yet. But i think we need some section where we explain how to use things,
in addition to un-opinionated api docs, that are mostly gernerated from interface declarations.

inventory-tutorial (handwritten) and inventory API (generated) are distinct sites for us.

The same applied to most sites:

one page api docs, auto generated
one page tutorial, for opinionated usage, manually maintained.

I added further explanation to the inventory there. Maybe the wording is not perfect yet. But i think we need some section where we explain how to use things, in addition to un-opinionated api docs, that are mostly gernerated from interface declarations. *inventory-tutorial* (handwritten) and *inventory API* (generated) are distinct sites for us. The same applied to most sites: one page api docs, auto generated one page tutorial, for opinionated usage, manually maintained.
hsjobeki commented 2024-07-19 09:18:12 +00:00
Owner
Copy Link

Merged this commit, with my proposed changes added in #1781

Merged this commit, with my proposed changes added in https://git.clan.lol/clan/clan-core/pulls/1781
hsjobeki closed this pull request 2024-07-19 09:18:12 +00:00
Some checks failed
buildbot/nix-build .#checks.aarch64-darwin.nixos-minimal-inventory-machine Build done.
Details
buildbot/nix-build .#checks.aarch64-linux.nixos-minimal-inventory-machine Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.nixos-minimal-inventory-machine Build done.
Details
buildbot/nix-build .#checks.aarch64-darwin.nixos-test_install_machine Build done.
Details
buildbot/nix-build .#checks.aarch64-darwin.nixos-test-inventory-machine Build done.
Details
buildbot/nix-build .#checks.aarch64-darwin.nixos-flash-installer Build done.
Details
buildbot/nix-build .#checks.aarch64-linux.nixos-test_install_machine Build done.
Details
buildbot/nix-build .#checks.aarch64-linux.nixos-test-inventory-machine Build done.
Details
buildbot/nix-build .#checks.aarch64-linux.nixos-flash-installer Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-app-no-breakpoints Build done.
Details
buildbot/nix-build .#checks.aarch64-darwin.nixos-test-backup Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.check-for-breakpoints Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-age Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-gui-installer-apk Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-gui-installer-rpm Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-avahi Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.devShell-docs Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.nixos-test-backup Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-e2fsprogs Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-module-docs Build done.
Details
buildbot/nix-build .#checks.aarch64-linux.nixos-test-backup Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.renderClanOptions Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-gui-installer-deb Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-gui-installer-archlinux Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-bash Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-git Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-mypy Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-nix Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-bubblewrap Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-openssh Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-pass Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-sops Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-util-linux Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-virtiofsd Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-app-pytest Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.devShell-clan-app Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-pytest-without-core Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-sshpass Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-tor Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-rsync Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-zbar Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-dep-qemu Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.treefmt Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.devShell-default Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.borgbackup Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.lib-jsonschema-example-valid Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.inventory-classes-up-to-date Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.devShell-webview-ui Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.container Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.lib-inventory-examples-cue Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.devShell-clan-cli Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.devShell-inventory-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-deploy-docs Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.deltachat Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.matrix-synapse Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-clan-cli Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-clan-cli-docs Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-clan-cli-full Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-clan-ts-api Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-classgen Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-default Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.nixos-test_install_machine Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-editor Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.nixos-test-inventory-machine Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-impure-checks Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-inventory-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-merge-after-ci Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.lib-jsonschema-nix-unit-tests Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-docs Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.module-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-tea-create-pr Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-clan-app Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-zerotier-members Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-webview-ui Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-zt-tcp-relay Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-inventory-schema-pretty Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-moonlight-sunshine-accept Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-pending-reviews Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-zerotierone Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.postgresql Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-function-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.wayland-proxy-virtwl Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.syncthing Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.lib-inventory-eval Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.module-clan-vars-eval Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.nixos-flash-installer Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-module-schema Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.secrets Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.zt-tcp-relay Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.template-minimal Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.package-gui-install-test-ubuntu-22-04 Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.test-backups Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.clan-pytest-with-core Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.flash Build done.
Details
buildbot/nix-build .#checks.x86_64-linux.test-installation Build done.
Details
buildbot/nix-eval Build done.
Required
Details
checks / checks-impure (pull_request) Failing after 3m11s
Required
Details

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
backups

   
blog

   
bootstrapping

Issues regarding bootstrapping, or onboarding

  
bug

Something is not working.

  
changes-requested

Please fix this.

  
cli

   
documentation

   
duplicate

This issue or pull request already exists

  
enhancement

New feature

  
facts

Issues regarding facts and secrets setting and generation

  
help wanted

Need some help

  
invalid

Something is wrong

  
Inventory

Inventory

  
low_prio

   
manager

   
modules

   
needs-review

This PR needs to be reviewed. Use the request-changes label to request changes

  
networking

   
packaging

   
question

More information is needed

  
secrets

   
template

Issues regarding templates.

  
test

Issues regarding testing

  
tooling

Issues regarding internal devtools

  
user-testing

Issues that cristallised after hands on user testing.

  
vm

Issues regarding virtual machines.

  
wontfix

This won't be fixed

No Label
backups
blog
bootstrapping
bug
changes-requested
cli
documentation
duplicate
enhancement
facts
help wanted
invalid
Inventory
low_prio
manager
modules
needs-review
networking
packaging
question
secrets
template
test
tooling
user-testing
vm
wontfix
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: clan/clan-core#1743
No description provided.
Delete Branch "fricklerhandwerk/clan-core:rearrange-docs-front"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?