Skip to content

Commit d6ab9e8

Browse files
author
Marek Suchánek
committed
Modularize the newdoc user documentation
1 parent ca3a6c0 commit d6ab9e8

10 files changed

+383
-291
lines changed

‎docs/assembly_generating-documentation-files.adoc

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
4+
ifdef::context[:parent-context-of-generating-documentation-files: {context}]
5+
6+
:_mod-docs-content-type: ASSEMBLY
7+
8+
ifndef::context[]
9+
[id="generating-documentation-files"]
10+
endif::[]
11+
ifdef::context[]
12+
[id="generating-documentation-files_{context}"]
13+
endif::[]
14+
= Generating documentation files
15+
16+
:context: generating-documentation-files
17+
18+
You can generate a documentation file outline that conforms to the modular templates.
19+
20+
include::proc_creating-a-new-module.adoc[leveloffset=+1]
21+
22+
include::proc_creating-a-new-assembly.adoc[leveloffset=+1]
23+
24+
include::proc_creating-a-new-snippet-file.adoc[leveloffset=+1]
25+
26+
include::proc_overwriting-existing-files.adoc[leveloffset=+1]
27+
28+
29+
ifdef::parent-context-of-generating-documentation-files[:context: {parent-context-of-generating-documentation-files}]
30+
ifndef::parent-context-of-generating-documentation-files[:!context:]
31+

‎docs/con_configuration-files.adoc

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
4+
:_mod-docs-content-type: CONCEPT
5+
6+
[id="configuration-files_{context}"]
7+
= Configuration files
8+
9+
You can store `newdoc` configuration in several configuration files. These adjust the same behavior that you can also set using command-line options.
10+
11+
The configuration files and arguments take the following precedence, from most important (overriding) to least important (overriden):
12+
13+
. The command-line arguments.
14+
15+
. A `.newdoc.toml` file in the Git repository where you generate the file.
16+
+
17+
If the Git repository is nested, `newdoc` looks for a configuration file in each repository, and the inner repository takes precedence over the outer one.
18+
19+
. A `newdoc.toml` file in your home directory, depending on your operating system:
20+
+
21+
Linux:: `~/.config/newdoc/newdoc.toml`
22+
macOS:: `/Users/__You__/Library/Application Support/com.Red-Hat.newdoc/newdoc.toml`
23+
Windows:: `C:\Users++\++__You__\AppData\Roaming\Red Hat\newdoc\config\newdoc.toml`
24+
25+
The configuration file has the following syntax:
26+
27+
[source,toml]
28+
----
29+
# These are the default values as of newdoc 2.18:
30+
comments = false
31+
examples = true
32+
metadata = true
33+
file_prefixes = true
34+
anchor_prefixes = false
35+
simplified = false
36+
----

‎docs/proc_creating-a-new-assembly.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="creating-a-new-assembly_{context}"]
6+
= Creating a new assembly
7+
8+
// Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization.
9+
10+
// .Procedure
11+
12+
. In the directory where assemblies are located, use `newdoc` to create a new file:
13+
+
14+
----
15+
assemblies-dir]$ newdoc --assembly "Achieving thing"
16+
----
17+
+
18+
You can use the short form of the `--assembly` option instead:
19+
+
20+
----
21+
assemblies-dir]$ newdoc -a "Achieving thing"
22+
----
23+
24+
. Rewrite the placeholders in the generated file with your docs.
25+
+
26+
Add AsciiDoc include statements to include modules. See [Include Files](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) in the AsciiDoc Syntax Quick Reference.
27+
+
28+
Alternatively, you can use the `--include-in` option when creating the assembly to generate modules and include them automatically, in a single step. See the description in the *Options* section.

‎docs/proc_creating-a-new-module.adoc

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="creating-a-new-module_{context}"]
6+
= Creating a new module
7+
8+
// Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization.
9+
10+
// .Procedure
11+
12+
. In the directory where modules are located, use `newdoc` to create a new file:
13+
+
14+
----
15+
modules-dir]$ newdoc --procedure "Setting up thing"
16+
----
17+
+
18+
The tool also accepts the `--concept` and `--reference` options. You can use these short forms instead: `-p`, `-c`, and `-r`.
19+
20+
. Rewrite the placeholders in the generated file with your docs.

‎docs/proc_creating-a-new-snippet-file.adoc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="creating-a-new-snippet-file_{context}"]
6+
= Creating a new snippet file
7+
8+
// Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization.
9+
10+
// .Procedure
11+
12+
. In the directory where snippets are located, use `newdoc` to create a new file:
13+
+
14+
----
15+
snippets-dir]$ newdoc --snippet "A reusable note"
16+
----
17+
+
18+
You can use the short forms instead:
19+
+
20+
----
21+
snippets-dir]$ newdoc -s "A reusable note"`
22+
----
23+
24+
. Rewrite the placeholders in the generated file with your docs.

‎docs/proc_installing-newdoc.adoc

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="installing-newdoc_{context}"]
6+
= Installing newdoc
7+
8+
You can install `newdoc` on various operating systems using several package managers.
9+
10+
.Fedora, RHEL, and CentOS
11+
12+
To install `newdoc` on current Fedora, RHEL 8 or later, or CentOS 8 or later, enable the Copr package repository:
13+
14+
. Enable the repository:
15+
+
16+
----
17+
# dnf copr enable mareksu/newdoc-rs
18+
----
19+
20+
. Install `newdoc`:
21+
+
22+
----
23+
# dnf install newdoc
24+
----
25+
+
26+
The Copr repository distributes packages only for *supported* releases of Fedora. If you have enabled the repository but the package fails to install, check if your Fedora is still supported.
27+
28+
.openSUSE Tumbleweed
29+
30+
To install `newdoc` on openSUSE Tumbleweed:
31+
32+
. Enable the Copr package repository:
33+
+
34+
----
35+
# zypper addrepo \
36+
'https://copr.fedorainfracloud.org/coprs/mareksu/newdoc-rs/repo/opensuse-tumbleweed/mareksu-newdoc-rs-opensuse-tumbleweed.repo'
37+
----
38+
39+
. Install `newdoc`:
40+
+
41+
----
42+
# zypper refresh
43+
# zypper install --allow-vendor-change newdoc
44+
----
45+
46+
.macOS
47+
48+
To install `newdoc` on macOS, use the **Homebrew** package manager:
49+
50+
. Install the **Homebrew** package manager as described on <https://brew.sh/>.
51+
52+
. Install `newdoc`:
53+
+
54+
----
55+
$ brew install msuchane/repo/newdoc
56+
----
57+
58+
.Container
59+
60+
To install `newdoc` as a container, use Docker or Podman.
61+
62+
[WARNING]
63+
--
64+
The `newdoc` container needs to access files in your host file system. It mounts your current directory into the container.
65+
66+
When the container runs, it relabels the SELinux configuration on all files in your current directory. This is necessary in order for the SELinux permissions system to enable file access on Fedora, RHEL, and CentOS.
67+
68+
As a consequence, you cannot run the `newdoc` container in certain directories specially protected by SELinux, such as at the root of your home directory.
69+
--
70+
71+
On Fedora, RHEL, and CentOS, replace `docker` with `podman` in the following commands:
72+
73+
. Download the image:
74+
+
75+
----
76+
$ docker pull quay.io/msuchane/newdoc
77+
----
78+
79+
. Configure a command alias. Save this line in your shell configuration file, such as in the `~/.bashrc` file:
80+
+
81+
----
82+
alias newdoc="docker run -it -v .:/mnt/newdoc:Z msuchane/newdoc newdoc"
83+
----
84+
85+
. Open a new terminal to reload the shell configuration.
86+
87+
. Test that `newdoc` works in a documentation directory:
88+
+
89+
----
90+
documentation-directory]$ newdoc
91+
----
92+
93+
NOTE: The default `newdoc` container is based on the Alpine distribution. If you need to install packages from the RHEL ecosystem in the `newdoc` container, you can use the `quay.io/msuchane/newdoc:distro` container variant. It is built on the RHEL 9 UBI Minimal base, and contains the `microdnf` package manager.
94+
95+
.From source on any platform
96+
97+
To install `newdoc` from source on a Linux distribution, on macOS, or on Microsoft Windows, use the `cargo` package manager:
98+
99+
. Install the Rust toolchain: see <https://rustup.rs/>.
100+
101+
. Install `newdoc`:
102+
+
103+
----
104+
$ cargo install newdoc
105+
----
106+
107+
.Verification
108+
109+
* Test that `newdoc` works:
110+
+
111+
----
112+
$ newdoc
113+
----

‎docs/proc_overwriting-existing-files.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="overwriting-existing-files_{context}"]
6+
= Overwriting existing files
7+
8+
When generating a new file, `newdoc` warns you if a file by that name already exists in this directory. It prompts you to choose an action.
9+
10+
.Procedure
11+
12+
* To overwrite the existing file with the new file, type `yes`.
13+
* To preserve the existing file and cancel the newly generated file, type `no`.

‎docs/proc_updating-newdoc.adoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="updating-newdoc_{context}"]
6+
= Updating newdoc
7+
8+
You can update `newdoc` with the package manager that you used to install it.
9+
10+
.Fedora, RHEL, and CentOS
11+
12+
To update `newdoc` that is installed from RPM on Fedora, RHEL, or CentOS, use the DNF package manager:
13+
14+
. Make sure that you are using a supported release of your Linux distribution. The Copr repository does not publish `newdoc` packages for unsupported distribution releases.
15+
16+
. Refresh repository metadata and update the package:
17+
+
18+
----
19+
# dnf --refresh upgrade newdoc
20+
----
21+
22+
.openSUSE
23+
24+
To update `newdoc` installed on openSUSE:
25+
26+
. Make sure that you are using a supported release of your Linux distribution. The Copr repository does not publish `newdoc` packages for unsupported distribution releases.
27+
28+
. Refresh repository metadata:
29+
+
30+
----
31+
# zypper refresh
32+
----
33+
34+
. Update the package:
35+
+
36+
----
37+
# zypper update newdoc
38+
----
39+
40+
.macOS
41+
42+
To update `newdoc` installed on macOS using **Homebrew**:
43+
44+
. Update the repository metadata:
45+
+
46+
----
47+
$ brew update
48+
----
49+
50+
. Update `newdoc`:
51+
+
52+
----
53+
$ brew upgrade newdoc
54+
----
55+
56+
.Container
57+
58+
To update the `newdoc` container, use Docker or Podman.
59+
60+
On Fedora, RHEL, and CentOS, replace `docker` with `podman` in the following command:
61+
62+
----
63+
$ docker pull quay.io/msuchane/newdoc
64+
----
65+
66+
.From source on any platform
67+
68+
To update `newdoc` from source, use the `cargo` package manager:
69+
70+
. Update the Rust toolchain:
71+
+
72+
----
73+
$ rustup update
74+
----
75+
76+
. Update `newdoc`:
77+
+
78+
----
79+
$ cargo install newdoc
80+
----

‎docs/ref_options.adoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:_newdoc-version: 2.18.2
2+
:_template-generated: 2024-06-05
3+
4+
:_mod-docs-content-type: REFERENCE
5+
6+
[id="options_{context}"]
7+
= Options
8+
9+
You can use several options on the command line to adjust the `newdoc` behavior.
10+
11+
.Command-line options
12+
* To generate the file with explanatory comments, add the `--comments` or `-M` option when creating documents.
13+
14+
* To generate the file without the example, placeholder content, add the `--no-examples` or `-E` option when creating documents.
15+
16+
* To generate the file without the metadata attributes header, add the `--no-metadata` or `-D` option when creating documents.
17+
18+
* By default, the content type prefix appears in the generated file name and not in the ID (anchor). To change this behavior, use the following options:
19+
+
20+
`--no-file-prefixes` or `-P`:: Disables the file-name prefix.
21+
`--anchor-prefixes` or `-A`:: Enables the ID (anchor) prefix.
22+
23+
* To specify the directory where `newdoc` saves the generated file, add the `--target-dir=<directory>` or `-T <directory>` option.
24+
25+
* To generate an assembly with include statements for other generated modules, use the `--include-in` or `-i` option:
26+
+
27+
----
28+
$ newdoc --include-in "An assembly for two modules" \
29+
--concept "First module" \
30+
--procedure "Second module"
31+
----
32+
+
33+
This creates the two modules and an assembly that features the include statements for the modules.

0 commit comments

Comments
 (0)