Generating help topics

The edm CLI offers detailed, inline help topics that can be accessed using edm help <topic>. A list of available topics can be found in the additional help topics section of edm --help. These help topics are auto-generated from the *.rst.inc files in doc/source/user.

Here is how you can add a new help topic:

  • Step 1: create a new .rst.inc file with the desired help content.

    The new file must be created in doc/source/user directory. For the purposes of these docs, lets call the newly created file newdoc.rst.inc. If you’d also like the contents of the new file to be added to the Sphinx documentation, you need to include the file in doc/source/user/cli.rst.

  • Step 2: modify the help topics Jinja template.

    You must tell Jinja the name under which you’d like the new help string to be available. To add the contents of newdoc.rst.inc to a topic called morehelp, the following statements would need to be added to edm/cli/topics.py.in:

    ...
    ...
    
    NEW_TOPIC = u"""\
    {{ newdoc }}"""
    
    TOPICS_HELP = {
        ...
        u"morehelp": (u"New help topic added by a developer", NEW_TOPIC),
        ...
    }
    
  • Step 3: add source file name to generator script.

    The help topic generator script in tools/regenerate_topics.py must now be made aware of the new source file it needs to consume. Add the name of the file, without the extension to the source_files variable:

    source_files = [..., "newdoc", ...]
    
  • Step 4: execute the generator script

    For successful execution of the generator script, you must have pandoc installed and available from the command line. Then, navigate to the project root folder and execute the script:

    $ python tools/regenerate_topics.py
    

    The new help topic should now be available from the edm CLI:

     $ edm --help
     ...
     Additional help topics:
       configuration  Learn how to configure EDM
       environment    Learn more about EDM environments
       intro          Quick start instructions for EDM
       morehelp       New help topic added by a developer
       proxy          Configuration instructions for users behind a proxy
    

Note

To modify an existing help topic, edit the corresponding .rst.inc file and repeat Step 4.