Improve documentation search results for important keywords

[vlcinsky]

Searching in existing doc for words such as:

• --seek-file
• -f
• doit.cfg
• DOIT_SEEK_FILE

provides no results.

Try to improve Sphinx based documentation so that this kind of keywords are described and found. Sphinx provides many "roles" such as :envvar:, :token:, :option:, :term:, :abbr:, :command:, :file: which are likely to put related words into search index.

[xordspar0]

@dkennedy2 and I would like to take a look at this. We'll start by tracking down the command line options and environment variables in the docs and tag them with the correct role.

[schettino72]

@xordspar0 @dkennedy2 thanks, that would be awesome.

There are 2 problems with current docs. First is the need to add Sphinx roles into existing references as you mentioned. Second is that many command line options are not even mentioned in docs... I was thinking about having a doit command that would generate a Sphinx formatted output of doit help <cmd>, and maybe even write a directive for that!

[xordspar0]

Cool, I like the idea of documentation for the cli interface being generated by code.

We've started adding roles in https://github.com/pydoit/doit/pull/289, but there's still more work to do there. Would it make sense to add all the roles in one PR and then make a second PR with the docs generation?

[xordspar0]

I made a PR specifically to add the :option: roles: https://github.com/pydoit/doit/pull/359

[xordspar0]

Progress of adding roles to existing documentation:

• [x] :envvar: – There currently aren't any environment variables in the documentation that I can see. We will write a doit command for generating that documentation.
• [x] :token: – This is for BNF grammars. doit doesn't have any BNF grammars in its documenation, so we won't do this.
• [x] :option: – We have a PR open for this: https://github.com/pydoit/doit/pull/359
• [ ] :term: – This is for defining glossary terms that must be defined. "If you use a term that’s not explained in a glossary, you’ll get a warning during build." This seems useful.
• [x] :abbr: – https://github.com/pydoit/doit/pull/360
• [x] :command: – I don't think this role does anything special, it just marks a command. Most of the docs already use .. code-block:: console directive instead, so I don't think it's necessary.
• [x] :file: – #361