Package: newdoc
DEPRECATED:This version ofnewdocis now deprecated and will no longer receive any significant updates. Please uninstall this version and migrate to the current version:https://github.com/redhat-documentation/newdoc.This script is used for generating empty module and assembly files when writing Red Hat or Fedora documentation in AsciiDoc. The generated files follow template guidelines set up by the Modular Documentation initiative:https://redhat-documentation.github.io/modular-docs/.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.How do I install the script?To installnewdocon Fedora or RHEL 8, use the Copr package repository:# dnf copr enable mareksu/newdoc
# dnf install python3-newdocOn a different Linux distribution that includes Python 3, use thepippackage manager, version 3:# pip3 install newdocOn RHEL 7, CentOS 7, or macOS, use thepippackage manager, version 2:# pip install newdocHow do I add a new module?In the directory where modules are located, use thenewdocscript to create a new file:modules-dir]$ newdoc --procedure "Setting up thing"Rewrite the information in the template with your docs.The script also accepts the--conceptand--referenceoptions. You can use these short forms instead:-p,-c, and-r.How do I add a new assembly?In the directory where assemblies are located, use thenewdocscript to create a new file:assemblies-dir]$ newdoc --assembly "Achieving thing"Rewrite the information in the template with your docs.Add AsciiDoc include statements to include modules. SeeInclude Filesin the AsciiDoc Syntax Quick Reference.You can use the short form of the--assemblyoption instead:newdoc-a"Achieving thing".Configurationnewdocenables 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 thenewdoc.iniconfiguration file, which is located:On Fedora, RHEL, and other Linux distributions, in~/.config/newdoc/newdoc.iniOn macOS, in~/Library/Preferences/newdoc/newdoc.iniThe 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 atexamples/newdoc.ini.Custom templatesIn the config file, you can set paths to custom AsciiDoc template files for each module type. The options are:assembly_templateconcept_templateprocedure_templatereference_templateFor example, to use a custom template for reference modules, use:reference_template = ~/.config/newdoc/my-reference-template.adocnewdocperforms substitutions on the templates using the Pythonstring.templatelibrary. 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 moduleFor more details on the template syntax, see:https://docs.python.org/3/library/string.html#template-stringsID substitutionsTheid_caseoption 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-caseid_case = capitalize: The first letter will be upper-case, the rest lower-caseid_case = preserve: Keep the capitalization as entered in the titleTheword_separatoroption lets you choose the symbol (or string) used to replace spaces in the ID. The default is a dash:word_separator = -NotesIf you prefernewdocto generate file without the explanatory comments, add the--no-commentsor-Coption when creating documents.Additional resourcesModular Documentation Reference GuideAsciiDoc Mark-up Quick Reference for Red Hat Documentation