Tools Overview How To

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 --generate_doc_tagged. The required output format and its content is described in the following.

--generate_doc_tagged

To be included in the overview a tool must support the --generate_doc_tagged command line argument. This is an example for expected output (taken from the autodoc tool):

<toolinfo>
   <name>autodoc</name>
   <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]
               {generate,dump,list}
         </usage>   
   <author>T.H.</author>
   <tags>doc,html,overview</tags>
   <version></version>   
   <documentation>https://www-acc.gsi.de/wiki/Frontend/AutoDoc</documentation>
   <environment></environment>
   <requires></requires>
   <autodocversion>1.0</autodocversion>
</toolinfo>

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

Items

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

Topics

The tools are grouped according to topics in the overview. The predefined topics are listed in the following table:

Equipment Access	autodoc.TOPIC_EQUIP_ACCESS
Device Information	autodoc.TOPIC_DEVICE_INFO
Maintenance	autodoc.TOPIC_MAINTENANCE
Development, Release, Rollout	autodoc.TOPIC_DEV_REL_ROLL
Helpers	autodoc.TOPIC_HELPERS
Others	autodoc.TOPIC_OTHERS

If possible tools should fit in one of the first 5 topics. Custom topics are also allowed they will be listed under Others 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.

I implemented --generate_doc_tagged for my tool. What now?

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

This will generate a file called mytool.wiki containing an "overview" for only mytool (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 pw (p for plain string overview, w 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).

-- TobiasHabermann - 03 Jul 2020