You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We use {antora-docs}[Antora] to write our user facing documentation,
10
19
{netlify}[Netlify] to host it and the {diataxis}[Diátaxis] framework as the guide for the structure of the content.
11
-
The main repository for the documentation is the {documentation}[Documentation] repository and
20
+
The main repository for the documentation is the {stackable-docs-repo}[Documentation] repository and
12
21
each operator and other tools have a `docs` directory from which content is pulled in.
13
22
Have a look at the xref:project-overview.adoc[] to learn about the repositories that are involved in providing the documentation.
14
23
15
24
== Content structure: Diátaxis
16
25
17
26
The {diataxis}[Diátaxis] framework is a way to classify documentation content into four groups with distinct use cases.
18
27
19
-
.Source: https://diataxis.fr/
28
+
.Source: {diataxis}
20
29
image::diataxis.png[]
21
30
22
31
Documentation exists along two axis: _study_ or _work_; _pracital steps_ and _theory_.
@@ -37,7 +46,7 @@ The guide has to account for different use-cases (i.e. the user is using their o
37
46
Since this kind of information is typically product specific, it is located in the usage guide section of individual operators.
38
47
39
48
**Reference** information for the Stackable platform entails all the settings and Options in our YAMLs, which we generate.
40
-
The reference is found at https://crds.stackable.tech/ and generated from the https://github.com/stackabletech/crddocs[crddocs repository].
49
+
The reference is found at {crddocs-site} and generated from the {stackable-crddocs-repo}[crddocs repository].
41
50
42
51
=== Style guide
43
52
@@ -46,16 +55,16 @@ The xref:docs/style-guide.adoc[] contains all the information about the writing
46
55
== Technical bits: Antora, Netlify, Pagefind
47
56
48
57
{antora-docs}[Antora] uses a {antora-playbook}[playbook] to build the documentation.
49
-
It pulls information from all the individual operators, so their documentation can live in the same repository.
58
+
It pulls documentation content from all the individual operator repositories, so an operators documentation is maintained in the same repository as the code.
50
59
Antora builds a static website which we serve over {netlify}[Netlify].
51
-
The web template of the documentation is also custom made and is developed in the https://github.com/stackabletech/documentation-ui[documentation-ui] repository.
60
+
The web template of the documentation is also custom made and is developed in the {stackable-docs-ui-repo}[documentation-ui] repository.
52
61
53
-
For search, we use https://pagefind.app/[pagefind] - a static search.
62
+
For search, we use {pagefind}[pagefind] - a static search.
54
63
The search index is generated as part of the build process and no external index is queried during search.
55
64
56
-
For Antora, the https://antora.zulipchat.com/[Antora Zulip chatroom] is a good place to get help (besides the documentation)!
65
+
For Antora, the {antora-zulipchat}[Antora Zulip chatroom] is a good place to get help (besides the documentation)!
57
66
58
-
Building the documentation and also the deployment process on Netlify are documented in the https://github.com/stackabletech/documentation/blob/main/README.adoc[README] file of the documentation repository.
67
+
Building the documentation and also the deployment process on Netlify are documented in the {stackable-docs-readme}[README] file of the documentation repository.
59
68
60
69
== Executable tutorials
61
70
@@ -76,9 +85,15 @@ This is used for getting started scripts, and in there only for versions of oper
76
85
77
86
Without this templating mechanism, every release these values would need to be updated by hand (or possibly with a search and replace) with is error prone and time consuming.
78
87
79
-
== Branch and version structure
88
+
== Branch, component and version structure
89
+
90
+
The documentation consists of two _components_, the `home` and `management` component.
91
+
All documentation for the operators is in the `home` component, and it is versioned with the platform versions (23.11, 24.3, 24.7 etc.).
92
+
The `management` component contains docs for `stackablectl` and the Stackable cockpit; it is not versioned (there is only a single, current version).
80
93
81
-
All Stackable repositories use https://trunkbaseddevelopment.com/[trunk based development], and so the documentation is also pulled from different release branches.
82
-
This means that any changes from the `main` branch that should be published in other versions need to be cherry-picked over into that branch.
94
+
The `home` component is actually a {antora-distributed-components}[distributed component], which means that it is split across multiple repositories.
95
+
Each operator repository has a `docs` directory where the docs are found, and in there the `antora.yml` file specifies that the component is `home`, which means that the `home` component is partially defined across all operator repositories.
83
96
84
-
Antora recommends using https://docs.antora.org/antora/latest/playbook/content-branches/[branches] to organize different versions of components.
97
+
For versions, all Stackable repositories use {trunk-based-development}[trunk based development], and so the documentation is also pulled from different release branches in each repository.
98
+
Each branch contains only a single version, and the `main` branch contains the `nightly` docs version.
99
+
Using branches to structure component version is also {antora-content-branches}[recommended by Antora].
* Netlify build error: `Duplicate nav in nightly@home: modules/ROOT/nav.adoc`
4
5
** This probably means that there are two branches of the same repository defined in the Antora playbook, that have the same version set.
5
6
They both supply a `nav.adoc` file for the same component and version, and Antora doesn't know which one to pick.
6
-
Make sure that the release branches have the correct version set in their `antora.yml` files and also make sure that the `main` branch is still set to `nightly`.
7
+
Make sure that the release branches have the correct version set in their `antora.yml` files and also make sure that the `main` branch is still set to `nightly`.
8
+
* An `xref` or `include` in the `home` component is not found (starting with `xref:home...`)
9
+
** If the page containing the `xref` is also in the `home` component, do **not** include the component name in the `xref`.
10
+
Read the {antora-xref-docs}[`xref` documentation].
11
+
Creating a reference to a page and _specifying a component without a version_ means that the link is pointing to the latest version.
12
+
This is usually not what you want!
13
+
Omitting the component entirely will instead link to the target page _within the same version_ as the page resides in.
14
+
* Other `xref` and `include` issues
15
+
** Familiarize yourself with the {antora-xref-docs}[`xref` documentation] which explains the syntax in great detail.
16
+
Unfortunately the xref syntax is a common place to make mistakes, and it is easy to accidently link to the wrong place.
0 commit comments