Docs: Split CLI section into invenio and invenio-cli with detailed command descriptions

[Samk13]

❤️ Thank you for your contribution!

Description

Closes: #719

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

• I'm aware of the code of conduct.
• I've created logical separate commits and followed the commit message format.
• I've targeted the master branch.
• If this documentation change impacts the current release of InvenioRDM, I will backport it to the production branch following approval or indicate to a maintainer that it should be backported.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

1. You license your contribution under the same terms as the current repository’s license.
2. You agree that you have the right to license your contribution under the current repository’s license.

[fenekku]

(would close this)

[fenekku]

Ah, we are not documenting the invenio command here. We only document the invenio-cli one. Those commands are called via the invenio command: e.g., invenio roles create ...

[Samk13]

Hmm, fair point, but from a user perspective, this is confusing. People running InvenioRDM don't care whether it's invenio or invenio-cli under the hood, they just want to know how to manage roles.
Since these commands are required to use core RDM functionality, they need to be documented somewhere in the RDM docs. If invenio CLI is the correct way, fine, let’s create a dedicated section like “invenio-cli and Invenio CLI” or similar sections and list the commands available.
Right now, it’s basically hidden.

[Samk13]

Ah, we are not documenting the invenio command here. We only document the invenio-cli one. Those commands are called via the invenio command: e.g., invenio roles create ...

Looking again at the CLI section, the claim that it's an invenio-cli only section isn’t accurate. It already includes commands that are actually invenio commands for example, invenio shell and invenio rdm. So we’re already documenting invenio commands directly in the CLI section.
If we’re exposing them to users, it makes sense to document them consistently rather than exclude some arbitrarily. I’ve created a dedicated section for invenio commands, so we can add these there in a clean and consistent way.

[fenekku]

Oups we shouldn't have put those there in the first place 😅 . The separate file as you have it is better.

[Samk13]

@fenekku
I’ve added a new section under CLI in the docs: invenio-cli and invenio. Previously, we only had a page for invenio-cli.
Now there’s a dedicated place for all invenio commands with high-level explanations, and thanks to AI, I was able to fill in the rest of the commands :P
In my opinion, this gives us room to expand, e.g., documenting the new i18n command, what it does, and how to use it.

The reality is: both invenio-cli and invenio are now needed to manage a running instance. We shouldn't treat one as secondary or expect users to look elsewhere for core functionality. The split section reflects that.
WDYT?

[fenekku]

Ah, yes creating a separate reference for the invenio commands is better 👍 . Hopefully this doesn't turn out to be too much to maintain with changes to those over time (like the invenio-cli commands reference can sometimes be unmaintained).

I also did some updates to the CLI section as part of the reorg I think, so overall that part will be much better. Thanks!

(There is a whole history of invenio / invenio-cli background, but yes invenio has always been required to operate an instance, so even if it is an Invenio-framework level command, I do agree it makes sense for us to document it)

[fenekku]

minor: Ultimately I think this is probably ok, although ironically invenio is the framework, and InvenioRdm with invenio-cli is the application/instance. Maybe reprise suggested wording above at first (but my recommendation is not that great either 🤷 )