mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-11-03 21:49:50 -09:00
doc: Add Antora configs
Adds Antora configuration so that a dedicated Cockpit Doc repo can access the various docs in Cockpit as well as an `antora-playbook.yml` file for local development purposes (without relying on Cockpit Doc). Partials in manpages were also renamed and restructured as Antora has a dedicated partial import mechanism to allow for more functionality. There were a few links in the nav files thar were not valid or pointed to wrong files. Most of these were just naming mismatches and has been changed to work with Antora. Nav files themselves also got the section anchors removed as there is little reason to showcase specific navigation items - instead section anchors should be used within pages themselves. Related-to: https://docs.antora.org/antora/latest/family-directories/ Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
This commit is contained in:
Freya Gustavsson
parent
bc62cb3709
commit
556097e052
18 changed files with 104 additions and 52 deletions
15
antora-playbook.yml
Normal file
15
antora-playbook.yml
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
site:
|
||||
title: Cockpit
|
||||
start_page: cockpit-guide:guide:index.adoc
|
||||
content:
|
||||
sources:
|
||||
# Cockpit
|
||||
- url: .
|
||||
branches: HEAD
|
||||
start_path: doc
|
||||
ui:
|
||||
bundle:
|
||||
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
|
||||
snapshot: true
|
||||
output:
|
||||
dir: ./doc/output/antora
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
if ENABLE_DOC
|
||||
|
||||
GUIDE_MAIN_ADOC_FILE = doc/modules/guide/cockpit-guide.adoc
|
||||
GUIDE_MAIN_ADOC_FILE = doc/modules/guide/bundling/cockpit-guide.adoc
|
||||
|
||||
GUIDE_ADOC_FILES = \
|
||||
doc/modules/guide/pages/api-base1.adoc \
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ EXTRA_DIST += \
|
|||
doc/modules/man/pages/cockpit-tls.8.adoc \
|
||||
doc/modules/man/pages/cockpit.conf.5.adoc \
|
||||
doc/modules/man/pages/pam_ssh_add.8.adoc \
|
||||
doc/modules/man/pages/partials/author.adoc \
|
||||
doc/modules/man/pages/partials/bugs.adoc \
|
||||
doc/modules/man/partials/author.adoc \
|
||||
doc/modules/man/partials/bugs.adoc \
|
||||
$(NULL)
|
||||
|
||||
MANPAGES = \
|
||||
|
|
|
|||
27
doc/README.md
Normal file
27
doc/README.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# Cockpit Docs
|
||||
|
||||
We have two distinct workflows for our docs, one relates to bundling documentation within Cockpit packages, the other regards online documentation for Cockpit with features for ease-of-use.
|
||||
|
||||
Explanation of existing directories and what their purpose is. Mostly follows an Antora designated directory design that is explained in [Antora folder structure](#antora-folder-structure).
|
||||
|
||||
```
|
||||
doc/ # All of Cockpit's doc is here; Plugins should be excluded.
|
||||
├── modules # Antora expects a module structure, irrelevant for AsciiDoctor.
|
||||
│ ├── guide # Cockpit Guide docs, encompasses everything that relates to Cockpit
|
||||
│ │ ├── bundling # Specific to AsciiDoctor bundling where we put single-page wrappers
|
||||
│ │ ├── pages # All pages that relate to Cockpit itself
|
||||
│ │ └── nav.adoc # Antora navigation file, displays pages from the file as a sidebar navigation for the specific component
|
||||
│ └── man # Cockpit man pages. Packaged as Manpages with AsciiDoctor, HTML with Antora.
|
||||
│ ├── pages # All manpages for packages distributed in cockpit
|
||||
│ ├── partials # Antora-designated folder, partials are imported by AsciiDoc manpages for Bugs, and Author
|
||||
│ └── nav.adoc # Antora navigation file, displays pages from the file as a sidebar navigation for the specific component
|
||||
└── antora.yml # Config for Antora to pickup that designates navigation files and attributes
|
||||
```
|
||||
|
||||
## Antora folder structure
|
||||
|
||||
Since Antora is a versatile documentation tool, they have structured directories for managing the modules and module-specific features - like pages and attachments.
|
||||
|
||||
> Antora assigns preset, content-specific behavior to the source files stored in the family directories.
|
||||
|
||||
https://docs.antora.org/antora/latest/family-directories/
|
||||
11
doc/antora.yml
Normal file
11
doc/antora.yml
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
name: cockpit-guide
|
||||
version: true
|
||||
title: Cockpit
|
||||
start_page: guide:index.adoc
|
||||
asciidoc:
|
||||
attributes:
|
||||
# Set by CLI option --attribute=cockpit-version=123
|
||||
cockpit-version: latest
|
||||
nav:
|
||||
- modules/guide/nav.adoc
|
||||
- modules/man/nav.adoc
|
||||
30
doc/modules/guide/bundling/cockpit-guide.adoc
Normal file
30
doc/modules/guide/bundling/cockpit-guide.adoc
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
= Cockpit documentation
|
||||
:leveloffset: 1
|
||||
|
||||
include::../pages/index.adoc[]
|
||||
|
||||
:leveloffset: 2
|
||||
|
||||
include::../pages/cockpit-manual.adoc[]
|
||||
|
||||
include::../pages/https.adoc[]
|
||||
|
||||
include::../pages/listen.adoc[]
|
||||
|
||||
include::../pages/startup.adoc[]
|
||||
|
||||
include::../pages/multi-host.adoc[]
|
||||
|
||||
include::../pages/authentication.adoc[]
|
||||
|
||||
include::../pages/sso.adoc[]
|
||||
|
||||
include::../pages/cert-authentication.adoc[]
|
||||
|
||||
include::../pages/privileges.adoc[]
|
||||
|
||||
:leveloffset: 1
|
||||
|
||||
include::../pages/features.adoc[]
|
||||
|
||||
include::../pages/development.adoc[]
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
= Cockpit documentation
|
||||
:leveloffset: 1
|
||||
|
||||
include::pages/guide.adoc[]
|
||||
|
||||
include::pages/features.adoc[]
|
||||
|
||||
include::pages/development.adoc[]
|
||||
|
|
@ -8,7 +8,6 @@
|
|||
* xref::cert-authentication.adoc[]
|
||||
* xref::privileges.adoc[]
|
||||
|
||||
[[features]]
|
||||
.Feature Internals
|
||||
* xref::feature-systemd.adoc[]
|
||||
* xref::feature-journal.adoc[]
|
||||
|
|
@ -25,10 +24,9 @@
|
|||
* xref::feature-sosreport.adoc[]
|
||||
* xref::feature-packagekit.adoc[]
|
||||
|
||||
[[cockpit-js]]
|
||||
.cockpit.js
|
||||
* xref::cockpit-cache.adoc[]
|
||||
* xref::cockpit-channel.adoc[]
|
||||
* xref::cockpit-channels.adoc[]
|
||||
* xref::cockpit-dbus.adoc[]
|
||||
* xref::cockpit-error.adoc[]
|
||||
* xref::cockpit-file.adoc[]
|
||||
|
|
@ -37,13 +35,13 @@
|
|||
* xref::cockpit-location.adoc[]
|
||||
* xref::cockpit-manifest.adoc[]
|
||||
* xref::cockpit-metrics.adoc[]
|
||||
* xref::cockpit-series.adoc[]
|
||||
* xref::cockpit-session.adoc[]
|
||||
* xref::cockpit-series-data.adoc[]
|
||||
* xref::cockpit-login.adoc[]
|
||||
* xref::cockpit-spawn.adoc[]
|
||||
* xref::cockpit-util.adoc[]
|
||||
|
||||
[[development]]
|
||||
.xref::api.adoc[]
|
||||
.xref::api-base1.adoc[]
|
||||
* xref::embedding.adoc[]
|
||||
* xref::packages.adoc[]
|
||||
* xref::urls.adoc[]
|
||||
|
|
|
|||
|
|
@ -1,27 +1,6 @@
|
|||
[[guide]]
|
||||
= Deployment Guide
|
||||
:leveloffset: {counter:leveloffset}
|
||||
|
||||
Documentation for Cockpit {cockpit-version}.
|
||||
|
||||
Latest version https://cockpit-project.org/guide/latest[available here].
|
||||
|
||||
include::cockpit-manual.adoc[]
|
||||
|
||||
include::https.adoc[]
|
||||
|
||||
include::listen.adoc[]
|
||||
|
||||
include::startup.adoc[]
|
||||
|
||||
include::multi-host.adoc[]
|
||||
|
||||
include::authentication.adoc[]
|
||||
|
||||
include::sso.adoc[]
|
||||
|
||||
include::cert-authentication.adoc[]
|
||||
|
||||
include::privileges.adoc[]
|
||||
|
||||
include::../leveloffset-helper.adoc[]
|
||||
|
|
|
|||
|
|
@ -35,11 +35,11 @@ command line.
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
||||
== See also
|
||||
|
||||
|
|
|
|||
|
|
@ -43,11 +43,11 @@ alternatives.
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
||||
== See also
|
||||
|
||||
|
|
|
|||
|
|
@ -103,11 +103,11 @@ configuration file.
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
||||
== See also
|
||||
|
||||
|
|
|
|||
|
|
@ -93,11 +93,11 @@ from. These are the files that are served to a non-logged in user.
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
||||
== See also
|
||||
|
||||
|
|
|
|||
|
|
@ -24,11 +24,11 @@ The bridge is started like a shell once per Linux user session.
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
||||
== See also
|
||||
|
||||
|
|
|
|||
|
|
@ -185,11 +185,11 @@ WarnBeforeConnecting=false
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
||||
== See also
|
||||
|
||||
|
|
|
|||
|
|
@ -38,8 +38,8 @@ password.
|
|||
|
||||
== Bugs
|
||||
|
||||
include::partials/bugs.adoc[]
|
||||
include::../partials/bugs.adoc[]
|
||||
|
||||
== Author
|
||||
|
||||
include::partials/author.adoc[]
|
||||
include::../partials/author.adoc[]
|
||||
|
|
|
|||
Loading…
Reference in a new issue