An overview of FE-Tools is automatically generated from output of the tools. The preliminary overview can be found here: https://www-acc.gsi.de/wiki/Frontend/ToolsOverview.
This page explains what has to be done to include a new tool in the overview. The overview is generated by a tool called autodoc
. This tool collects information from other tools by calling them via the command line argument
. The required output format and its content is described in the following.
To be included in the overview a tool must support the
command line argument. This is an example for expected output (taken from the autodoc tool):
<topic>Development, Release, Rollout</topic>
<description>Generate tools overview from output of autodoc enabled tools</description>
<usage>autodoc [-h] [--tools_dir TOOLS_DIR] [--html HTML] [--dump DUMP]
[--search SEARCH] [--black_list BLACK_LIST] [--verbose]
- The individual items are explained in detail in the next section.
- Each item is surrounded by <name of item> and </name of item>
- The whole block is surrounded by <toolinfo> and <toolinfo>. Any output outside of those tags is ignored.
- The items can appear in any order.
- Blank items can be left out. (mandatory items, see below, should not be blank)
- There is support for generating the output in python and bash scripts, see autodoc for details.
The predefined items are listed in the following table:
| ||item ||from Parser ||description |
|mandatory ||name ||x ||Name of the tool |
|topic || ||Choose a predefined topic (see above). Custom topics are allowed. |
|description ||x ||Short description. This should fit on a single line. |
|usage ||x ||Similar to what you get from --help (only list of arguments, no detailed description) |
|author || ||Author of the tool |
|optional ||tags || ||Tags help for "findability". For example a tool that uses a GUI to display timing information could be tagged as "graphics,interactive,timing" |
|version ||x ||The version of the tool |
|documentation || ||The overview itself should be terse and short. More detailed documentation can be linked here |
|environment || ||Some tools can/should only be using in a certain environment. The item can hold arbitrary string, but one should use dev/int/pro. |
|requires || ||Some tools have preconditions to be used. For example snoopy-rec requires the WRSnoop FESA Class to be running. Listing requirements here can help users in case of failure/errors |
|more || ||The predefined items should be sufficient for the overview. If a tool author still feels the need to add a custom item, they can do so. Item names may not contain whitespaces. |
|hidden ||autodocversion || ||Version of autodoc that was used to generate the output. |
- Mandatory items are always included in the overview even when they are empty (they should not be empty).
- Optional items are only included in the overview when they are not empty.
- Hidden items are for autodoc internal use only. Currently there is only one item: autodocversion (cf. autodoc).
- The "from Parser" column indicates whether the item supports the
autodoc.FROM_PARSER tag (cf. autodoc).
The tools are grouped according to topics in the overview. The predefined topics are listed in the following table:
|Equipment Access || |
|Device Information || |
|Maintenance || |
|Development, Release, Rollout || |
|Helpers || |
|Others || |
If possible tools should fit in one of the first 5 topics. Custom topics are also allowed they will be listed under
in the overview. The second column lists the symbols defined in autodoc
Items Details & Recommendations
This section lists tips and recommendations that are not enforced, but should be considered when writing the tools information for the overview:
- The tools overview is not supposed to replace dedicated documentation. The toolinfo for the overview should be short and concise.
- Mandatory items: should always have a value
- name: The name should be identical to the command used to invoke the tool.
- topic: It is recommended to choose a predefined topic. Here you can find examples of what tool fit into what topic from the overview of the old tools https://www-acc.gsi.de/wiki/Frontend/BelTools. If you think a topic is not specific enough you can use tags to be more specific.
- description: A recommandation from python (PEP257) applies here: "It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".". Example: For a tool that foos the bar, bad: "This is a tool that enables you to foo the bar" (too verbose), good: "Foo the bar".
- usage: Do not describe what the command line arguments do, only list them.
- author: You can use initials. If there is ambiguity use your full name.
- Optional Items: are only included in the overview when they are not blank. Do not use values like "none" (eg for documentation) or "any" (eg environment), instead leave the item empty if it does not apply in your case.
- tags: use all lower-case, seperated by commas. Tags are supposed to help with searching, hence reuse tags when applicable and try to be consistent (eg bad: "front-end" and "frontend"). Browse existing tags to see if you can use any of them for your tool.
- version: This item can be used to document the version of your tool. This need not reflect minor changes of the tool, ie only the major version number.
- documentation: Do not put free text here, only a single url.
- environment: If the tool is agnostic of the environment this field should be left empty. For tools that can be used in any environment, but do depend on other components to be fully functional you can use "int/dev/pro".
- requires: Do not list obvious dependencies here (eg "acc network"), some dependencies are obvious to you but maybe not to others (eg "fesa-db")
- more: The possibility to add custom items exists mainly for forward compatibility. Adding custom items should be used with caution. If a new item turns out to be needed, it should be considered to be integreated as mandatory/optional item for all tools.
The overview here in the wiki uses a blacklist of old tools that do not support autodoc. If you upgraded an old tool it has to be removed from that blacklist. If your tools is new and installed in the FE-Tools folder, nothing has to be done. The tool will be included in the overview on the next update.
If you want to see how your tool will appear in the final output, you can use the autodoc
This will generate a file called
containing an "overview" for only
(only one entry, but inclding table of contents and section for topics):
autodoc generate --tools /path/to/mytool/mytool --outputfile mytool --format wiki
To get only the entry of your tool as wiki content (ie no table of contents, no sections for topics) the format is
for plain string overview,
for wiki formatting of entries), the output will be stored in mytool.pw (eg here
you can find an example of wiki content that was generated in this way).
- 03 Jul 2020