Organize flags in docs into categories

[smathermather]

Looking through, in particular, https://github.com/OpenDroneMap/docs/blob/publish/source/using.rst there's some opportunity to better organize the command line flags into categories so that people can look for something they want to accomplish and then choose the relevant flags.

[Saijin-Naib]

What does everyone think about "tags" for each parameter?

We could have a tag for larger conceptual/product groups (DEM, Orthophoto, PointCloud, Features, etc) and maybe pipeline stages (Matching, Extraction, Densification, etc)?

I'm trying to think about how I'd like to group the main arguments landing page, and further, whether or not these "tags" might help on the full arguments_edit subpage to give folks an idea of where each piece sort of fits in the context of the overall larger puzzle?

The only thing that has me concerned with this at the moment is that it likely requires a rework of our extract_strings.py script to group/order things properly.

[danbjoseph]

I'm happy to help try and rewrite any of the scripts or figure out how otherwise to make it happen. I think tags would help. I think making it functional in a way that it's useful for the reader will be difficult. With 2+ tag categories, it would help to have some sort of interactive filtering on the arguments page - but I think that pushes beyond what sphinx expects a developer to do and so would require a probably hacky workaround? and is also likely to get complicated with the translations.

[Saijin-Naib]

Thanks for the help with the heavy lifting, Dan!

Do you think we'd need the filtering if we use the two tag categories proposed above as sort of a means to arrange/group/sort the flags on the arguments page in a hierarchical manner? I think in this context, they'd sort of be more a visual aide than anything, as we could likely use regular rST markup to sort of arrange things on the page logically.

Would an aggregated page for each tag work as an index, without requiring filtering? I think we can do that by making a special rST role for the tags, right? And linking back to that arguments_tag1 or arguments_tag2 page when clicking on the tag?

[pierotofy]

+1 for tags. I'm unsure about explicit categories, we have many flags that don't fit into any specific category, or could be considered part of multiple categories (not saying it wouldn't help to have categories, just saying it could be tricky to do it effectively).

[Saijin-Naib]

Makes sense, and something I was struggling with, as well. What would you recommend in that regard?

[pierotofy]

Assign one or more tags to each option.

Then allow the options docs to be browsed / searched by tag.

Options --> By Tag --> [Tags] --> [List of options]

Leaving the ability to browse them alphabetically as-is as well ?

[danbjoseph]

Does that look like a section header for "all" and then a section for each tag? With an individual option appearing in the all list and then in one or more of the tag lists?

Or are you thinking of some sort of dynamic or interactive searching/ filtering (i.e. something that would require JavaScript)?

[Saijin-Naib]

At this point, I'm not thinking of any dynamic search/filtering. I think a static page for each tag type that lists all the parameters with that tag? Sort of like how the highest-level agruments page lists everything below it?

We'd have a tag page for texturing,meshing,feature detection, and so on.

[pierotofy]

With an individual option appearing in the all list and then in one or more of the tag lists?

That's what I was thinking, yes. No Javascript.

[Saijin-Naib]

So, what would be the best way to tag the various arguments? Add a tag into the code in the config.py in a certain format that we can detect/parse out using the extract_stings.py script?

[pierotofy]

That's an approach, or just a JSON file with "option" --> [tags] mapping directly in this repo.

[Saijin-Naib]

With that JSON, the extract_strings.py will be modified to read and parse it and then place the tags on matching argument rst pages?

Is there a flavor/type of JSON, or do they not really work that way?

[pierotofy]

JSON is standard (no flavors).

An example:

{
"--feature-type": ["structure-from-motion", "another-tag", "etc"]
}

[Saijin-Naib]

Perfect, thank you! That helps me tons.

[Saijin-Naib]

So, in this implementation, we would just have an ordered/unordered list of tags for each argument, right? There'd be no different categories for tags?

Would that be tenable by formatting the tags somehow? Or is that not something we need since having multiple tag categories isn't desired?