newdoc 1.2

A script to generate assembly and module AsciiDoc files from templates.

:toc:

[id="readme"]
= README: The `newdoc` script

[id="installation"]
== How do I install the script?

The script is now compatible with both Python 3 (for Fedora and community distributions) and Python 2.7 (for RHEL 7 and macOS).

It hasn't been tested on Windows.

[discrete]
=== Procedure

. Clone this repository somewhere on your system:
+
[subs=+quotes]
----
$ git clone [e-mail]:ccs-tools/newdoc.git
----

. In your shell configuration, add an alias to the `newdoc` script.
+
** If you are using Fedora or a community Linux distribution:
+
[subs=+quotes]
----
alias newdoc="python**3** _path-to-cloned-repo_/newdoc.py"
----
+
For example, if you are using the `bash` shell, you might add something like the following in your `~/.bashrc` file:
+
[subs=+quotes]
----
alias newdoc="python3 __/home/msuchane/RH/newdoc/__newdoc.py"
----

** If you are using RHEL 7:
+
[subs=+quotes]
----
alias newdoc="python**2** __/home/msuchane/RH/newdoc/__newdoc.py"
----
+
For example, if you are using the `bash` shell, you might add something like the following in your `~/.bashrc` file:
+
[subs=+quotes]
----
alias newdoc="python2 __/home/msuchane/RH/newdoc/__newdoc.py"
----

** If you are using macOS:
+
[subs=+quotes]
----
alias newdoc="python**2** __/Users/msuchane/RH/newdoc/__newdoc.py"
----
+
For example, if you are using the `bash` shell, you might add something like the following in your `~/.bashrc` file:
+
[subs=+quotes]
----
alias newdoc="python2 __/Users/msuchane/RH/newdoc/__newdoc.py"
----

[discrete]
=== Notes

* If you prefer `newdoc` to generate file without the explanatory comments, change the alias to include the `--no-comments` option:
+
[subs=+quotes]
----
alias newdoc="_python3_ __/home/msuchane/RH/newdoc/__newdoc.py *--no-comments*"
----

* In order for the alias to take effect in your current shell session as well, reload the configuration file. For example, with `bash`:
+
----
$ source ~/.bashrc
----

[id="new-module"]
== How do I add a new module?

[discrete]
=== Prerequisites

* Install the script. See xref:installation[] for details.

[discrete]
=== Procedure

. In the directory where modules are located, use the `newdoc` script to create a new file:
+
[subs=+quotes]
----
_modules-dir_]$ newdoc _--procedure_ "_Setting up thing_"
----
+
The script also accepts the `--concept` and `--reference` options. You can use these short forms instead: `-p`, `-c`, and `-r`.

. Rewrite the information in the template with your docs.

[id="new-assembly"]
== How do I add a new assembly?

[discrete]
=== Prerequisites

* Install the script. See xref:installation[] for details.

[discrete]
=== Procedure

. In the directory where assemblies are located, use the `newdoc` script to create a new file:
+
[subs=+quotes]
----
_assemblies-dir_]$ newdoc --assembly "_Achieving thing_"
----
+
You can use the short form of the option instead: `newdoc -a "_Achieving thing_"`.

. Rewrite the information in the template with your docs.
+
Add AsciiDoc include statements to include modules. See link:https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[Include Files] in the AsciiDoc Syntax Quick Reference.


[id="configuration"]
== Configuration

`newdoc` enables you to configure multiple aspects of its behavior:

* Custom templates for assemblies and modules,
* How IDs are capitalized when converted from a title,
* What symbol is used to replace spaces in IDs.

These options can be set in the `newdoc.ini` configuration file, which is located:

* On Fedora, RHEL, and other Linux distributions, in `~/.config/newdoc/newdoc.ini`
* On macOS, in `~/Library/Preferences/newdoc/newdoc.ini`

The configuration file is not created automatically: if you want to set custom options, create it using a plain text editor.

The file must always start with the `[newdoc]` header. An example configuration is available in this repo at `examples/newdoc.ini`.


[discrete]
=== Custom templates

In the config file, you can set paths to custom AsciiDoc template files for each module type. The options are:

* `assembly_template`
* `concept_template`
* `procedure_template`
* `reference_template`

For example, to use a custom template for reference modules, use:

[subs=+quotes]
----
reference_template = _~/.config/newdoc/my-reference-template.adoc_
----

`newdoc` performs substitutions on the templates using the Python `string.template` library. The following strings are replaced:

* `${module_title}` with the entered title of the module
* `${module_id}` with the generated ID of the module
* `${filename}` with the generated file name of the module

For more details on the template syntax, see: link:https://docs.python.org/3/library/string.html#template-strings[]


[discrete]
=== ID substitutions

* The `id_case` option in the config file controls how the letter case should change from the title to the ID:
+
`id_case = lowercase`:: All letters in the ID will be lower-case
`id_case = capitalize`:: The first letter will be upper-case, the rest lower-case
`id_case = preserve`:: Keep the capitalization as entered in the title

* The `word_separator` option lets you choose the symbol (or string) used to replace spaces in the ID. The default is a dash:
+
----
word_separator = -
----

== Additional resources

* link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide]
* link:https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Red Hat Documentation]