Modularize Foreman API guide

maximiliankolb commented 1 month ago

What changes are you introducing?

Modularize content in guides/common/modules related to the Foreman API guide
Unifying anchors: Is a original effort by Lena to bring the Foreman API guide upstream, we briefly discussed to way to set anchors. If I remember correctly, we though about using the api- prefix similar to the cli- prefix for CLI procedures. I consider this to have value on its own; and allow for a smoother transition in case we ever decide that we want to also show the API procedure as part of "normal aka. WebUI-based" workflows.
Using long options for commands (mostly curl) to provide better readability
Using one argument per line to also simplify readability

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

mostly to improve maintainability by splitting content into smaller modules. to align with existing content; help downstream integration; to prepare for the eventual merge with WebUI related procedures.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Refs https://github.com/theforeman/foreman-documentation/pull/3212/files#r1746164481
I would like your opinion on "=" vs "." headings. If we have a consensus, I'd be happy to implement this as part of this PR.
Do we want to keep --request GET for curl commands? It's the default HTTP method and the command would also work without.
Do we want to use single or double quotes for quotes commands? I did not yet actively try to unify this but would if someone makes a proposal and is willing to review :smiley:

Checklists

[x] I am okay with my commits getting squashed when you merge this PR.
[x] I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

[ ] Foreman 3.12/Katello 4.14 (Satellite 6.16)
[ ] Foreman 3.11/Katello 4.13
[ ] Foreman 3.10/Katello 4.12
[ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
[ ] Foreman 3.8/Katello 4.10
[ ] Foreman 3.7/Katello 4.9 (Satellite 6.14)
[ ] Foreman 3.6/Katello 4.8
[ ] Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
We do not accept PRs for Foreman older than 3.5.

github-actions[bot] commented 1 month ago

The PR preview for 40397d652c11a31f1a018cfa9e59745e60df446d is available at theforeman-foreman-documentation-preview-pr-3353.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

Lennonka commented 1 month ago

Do we want to keep --request GET for curl commands?

I'd suggest to keep it for clarity because some endpoints can be accessed by using multiple methods and it's more descriptive to be explicit about the method in use even if it's the default one.

Lennonka commented 1 month ago

Do we want to use single or double quotes for quotes commands?

I'm assuming you mean inside the Python and Ruby code. Assuming they won't change the functionality (if they are semantically same), we might go with " (double quotes) because it looks like they are used more frequently in the code and are better for readability.

However, this requires a more in-depth research as to the semantics of the code IMHO. Perhaps even developer review.

maximiliankolb commented 2 weeks ago

Rebased to "master", resolved a merge conflict, and reverted a change "MB -> MiB".

maximiliankolb commented 1 week ago

Merged to "master" and cherry-picked to "3.13": 17f6cb784d..d657a19a31 3.13 -> 3.13

Thanks to everyone for their input. @apinnick @Lennonka @asteflova If you want to propose any follow-up changes, esp. to procedures about "applying errata" (we have a lot of these!), ping me. I could also open an upstream issue and look into this myself soon.

theforeman / foreman-documentation