The newdoc
tool generates pre-populated module and assembly files formatted with AsciiDoc, which are used in Red Hat and Fedora documentation. The generated files follow the Modular Documentation guidelines: https://redhat-documentation.github.io/modular-docs/.
1. Installing newdoc
You can install newdoc
on various operating systems using several package managers.
1.1. Fedora, RHEL, and CentOS
To install newdoc
on current Fedora, RHEL 8 or later, or CentOS 8 or later, enable the Copr package repository:
-
Enable the repository:
# dnf copr enable mareksu/newdoc-rs
-
Install
newdoc
:# dnf install newdoc
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.
1.2. openSUSE Tumbleweed
To install newdoc
on openSUSE Tumbleweed:
-
Enable the Copr package repository:
# zypper addrepo \ 'https://copr.fedorainfracloud.org/coprs/mareksu/newdoc-rs/repo/opensuse-tumbleweed/mareksu-newdoc-rs-opensuse-tumbleweed.repo'
-
Install
newdoc
:# zypper refresh # zypper install --allow-vendor-change newdoc
1.3. macOS
To install newdoc
on macOS, use the Homebrew package manager:
-
Install the Homebrew package manager as described on https://brew.sh/.
-
Install
newdoc
:$ brew install msuchane/repo/newdoc
1.4. Container
To install newdoc
as a container, use Docker or Podman.
Warning
|
The 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. As a consequence, you cannot run the |
On Fedora, RHEL, and CentOS, replace docker
with podman
in the following commands:
-
Download the image:
$ docker pull quay.io/msuchane/newdoc
-
Configure a command alias. Save this line in your shell configuration file, such as in the
~/.bashrc
file:alias newdoc="docker run -it -v .:/mnt/newdoc:Z msuchane/newdoc newdoc"
-
Open a new terminal to reload the shell configuration.
-
Test that
newdoc
works in a documentation directory:documentation-directory]$ newdoc
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.
|
1.5. From source on any platform
To install newdoc
from source on a Linux distribution, on macOS, or on Microsoft Windows, use the cargo
package manager:
-
Install the Rust toolchain: see https://rustup.rs/.
-
Install
newdoc
:$ cargo install newdoc
-
Test that
newdoc
works:$ newdoc
2. Updating newdoc
You can update newdoc
with the package manager that you used to install it.
2.1. Fedora, RHEL, and CentOS
To update newdoc
that is installed from RPM on Fedora, RHEL, or CentOS, use the DNF package manager:
-
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. -
Refresh repository metadata and update the package:
# dnf --refresh upgrade newdoc
2.2. openSUSE
To update newdoc
installed on openSUSE:
-
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. -
Refresh repository metadata:
# zypper refresh
-
Update the package:
# zypper update newdoc
2.3. macOS
To update newdoc
installed on macOS using Homebrew:
-
Update the repository metadata:
$ brew update
-
Update
newdoc
:$ brew upgrade newdoc
2.4. Container
To update the newdoc
container, use Docker or Podman.
On Fedora, RHEL, and CentOS, replace docker
with podman
in the following command:
$ docker pull quay.io/msuchane/newdoc
2.5. From source on any platform
To update newdoc
from source, use the cargo
package manager:
-
Update the Rust toolchain:
$ rustup update
-
Update
newdoc
:$ cargo install newdoc
3. Generating documentation files
You can generate a documentation file outline that conforms to the modular templates.
3.1. Creating a new module
-
In the directory where modules are located, use
newdoc
to create a new file:modules-dir]$ newdoc --procedure "Setting up thing"
The tool also accepts the
--concept
and--reference
options. You can use these short forms instead:-p
,-c
, and-r
. -
Rewrite the placeholders in the generated file with your docs.
3.2. Creating a new assembly
-
In the directory where assemblies are located, use
newdoc
to create a new file:assemblies-dir]$ newdoc --assembly "Achieving thing"
You can use the short form of the
--assembly
option instead:newdoc -a "Achieving thing"
. -
Rewrite the placeholders in the generated file with your docs.
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.
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.
3.3. Creating a new snippet file
-
In the directory where snippets are located, use
newdoc
to create a new file:snippets-dir]$ newdoc --snippet "A reusable note"
You can use the short forms instead:
newdoc -s "A reusable note"
. -
Rewrite the placeholders in the generated file with your docs.
3.4. Overwriting existing files
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:
-
Overwrite the existing file with the new file.
-
Preserve the existing file and cancel the newly generated file.
4. Options
-
To generate the file with explanatory comments, add the
--comments
or-M
option when creating documents. -
To generate the file without the example, placeholder content, add the
--no-examples
or-E
option when creating documents. -
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:
--no-file-prefixes
or-P
-
Disables the file-name prefix.
--anchor-prefixes
or-A
-
Enables the ID (anchor) prefix.
-
To specify the directory where
newdoc
saves the generated file, add the--target-dir=<directory>
or-T <directory>
option. -
To generate an assembly with include statements for other generated modules, use the
--include-in
or-i
option:$ newdoc --include-in "An assembly for two modules" \ --concept "First module" \ --procedure "Second module"
This creates the two modules and an assembly that features the include statements for the modules.
5. Configuration files
You can store newdoc
configuration in several configuration files. These adjust the same behavior that you can also set using command-line options.
The configuration files and arguments take the following precedence, from most important (overriding) to least important (overriden):
-
The command-line arguments.
-
A
.newdoc.toml
file in the Git repository where you generate the file.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. -
A
newdoc.toml
file in your home directory, depending on your operating system:- Linux
-
~/.config/newdoc/newdoc.toml
- macOS
-
/Users/You/Library/Application Support/com.Red-Hat.newdoc/newdoc.toml
- Windows
-
C:\Users\You\AppData\Roaming\Red Hat\newdoc\config\newdoc.toml
The configuration file has the following syntax:
# These are the default values as of newdoc 2.17:
comments = false
examples = true
file_prefixes = true
anchor_prefixes = false
simplified = false