newdoc 1.2.3

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

# README: The newdoc script

## 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.

To install newdoc, use the pip package manager:

` $ pip --user install newdoc `

## How do I add a new module?

1. In the directory where modules are located, use the newdoc script to create a new file:

   ` 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.

2. Rewrite the information in the template with your docs.

## How do I add a new assembly?

1. In the directory where assemblies are located, use the newdoc script to create a new file:

   ` assemblies-dir]$ newdoc --assembly "Achieving thing" `

   You can use the short form of the option instead: newdoc -a “Achieving thing”.

2. Rewrite the information in the template 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.

## 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.

### 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:

` 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: <https://docs.python.org/3/library/string.html#template-strings>

### 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 = - `

## Notes

• If you prefer newdoc to generate file without the explanatory comments, add the –no-comments or -C option when creating documents.

## Additional resources

• [Modular Documentation Reference Guide](https://redhat-documentation.github.io/modular-docs/)

• [AsciiDoc Mark-up Quick Reference for Red Hat Documentation](https://redhat-documentation.github.io/asciidoc-markup-conventions/)