Add workflows documentation page

[gerrod3]

fixes: #395

[mdellweg]

Wow, this looks like a lot of work.
Are the feature tables autogenerated?

[gerrod3]

Wow, this looks like a lot of work. Are the feature tables autogenerated?

No, but I was looking into it. I just couldn't decide what would be the best approach.

1. Put comments in the code for operation ids of commands and have a linter figure out each command and their corresponding API call.
2. Add a field to PulpCommand that would store the operation id. It would be set manually on command initialization and the command factories would populate this using a callback for their specific entity context. Then have a debug command run through all the commands and print out their corresponding operation id.

The big problem I couldn't decide on was how to handle commands that could call different endpoints based on their field options. Wasn't sure what would be the best way to reflect that in an auto-generated table.

[mdellweg]

Actually, i am concerned this level of detail may be too much (both for digesting and for keeping up to date).
What i really like about this is that we list all the workflow links for plugin specific docs, as well as the "use --help to find yourself around". The latter has the benefit that it is always accurate to the users installation.

[gerrod3]

Yeah the tables might be a bit much. The other idea I had for the features section was creating a list of objects for each plugin and putting the operations that the CLI can perform on them, e.g.

C=Create, R=Read, U=Update, D=Destroy

1. File content - CR
2. File distributions - CRUD
3. File publications - CRD
4. File remotes - CRUD
5. File repositories - CRUD, Sync, Modify

[mdellweg]

I would try to avoid adding html tags.

[ggainey]

I did some testing after our discussions this week, I have two suggestions:

• bold the 'verb' entries, to make them stand out more, so the reader can see at a glance "what's working"
• add this page to mydocs.,yml so it show up in the menu

[ggainey]

Would still like to see the CRUD indicators in bold, as well as fixing the Workflows-lists.

[ggainey]

This built as a single paragraph for some reason - resulting HTML (at least on my box):

<p>The CLI currently supports the following workflows:
  * <a href="https://docs.pulpproject.org/pulpcore/workflows/upload-publish.html"><strong>Uploading</strong> Artifacts</a>
  * <a href="https://docs.pulpproject.org/pulpcore/workflows/exposing-content.html"><strong>Creating, Syncing, Distributing</strong> Content</a>
  * <a href="https://docs.pulpproject.org/pulpcore/workflows/import-export.html#exporting"><strong>Exporting</strong> Content</a>
  * <a href="https://docs.pulpproject.org/pulpcore/workflows/labels.html"><strong>Labeling</strong> Resources</a></p>

[ggainey]

Same here as above - in fact, all the Workflows sections. I think they need a blank line before the lists?

[gerrod3]

Would still like to see the CRUD indicators in bold, as well as fixing the Workflows-lists.

My bad, I wasn't thinking of the CRUD indicators as verbs. Should the letters in the keys also be bolded?

[ggainey]

Would still like to see the CRUD indicators in bold, as well as fixing the Workflows-lists.

My bad, I wasn't thinking of the CRUD indicators as verbs. Should the letters in the keys also be bolded?

Hm - I'm not sure we need to. What I'm mostly after here, is to pull the eye to the end of the line and separate the "these are implemented" from "this is the object" - does that make sense?

[ggainey]

Changes look great, thanks!

[fkuep]

Thanks @gerrod3 !!
Looking over the document, I can see links to the workflows in the plugins documentation , which most times use the http binary instead of pulp-cli.
Since the server plugins are out-of-tree of pulp-cli pulp-cli/tree/main/tests/scripts serve as integration tests right ?
Should the tests like tests/scripts/pulp_ansible/test_content.sh , have a comment like : docs/supported_workflows.md#pulp_ansible : Role content / Collection content
to track what is really known to work, with a certain release ?

@mdellweg with the addition of docs/supported_workflows.md pulp-cli now has authorative ,versioned information on what it can do ...
does @melcorr know already she can point to it from https://github.com/pulp/pulpproject.org/blob/gh-pages/content-plugins.md#pulp-3-cli-coverage ?

[gerrod3]

Thanks @gerrod3 !! Looking over the document, I can see links to the workflows in the plugins documentation , which most times use the http binary instead of pulp-cli. Since the server plugins are out-of-tree of pulp-cli pulp-cli/tree/main/tests/scripts serve as integration tests right ? Should the tests like tests/scripts/pulp_ansible/test_content.sh , have a comment like : docs/supported_workflows.md#pulp_ansible : Role content / Collection content to track what is really known to work, with a certain release ?

Yes it is up to the plugin writers to change their workflows to use the CLI. Currently pulp_ansible, pulp_file, and pulp_python, have CLI workflows. Some of the pulpcore workflows have been converted, but none of the pulp_container or pulp_rpm have been. It's my goal to work on converting those last 2 plugins next. The tests are currently used as integration tests if they have test_cli set. The tests don't have much visibility to regular users, so I'm not sure how helpful putting comments in them will be.

[fkuep]

. The tests are currently used as integration tests if they have test_cli set.

Yes - OK - Great!
.. thats way better !