[PATCH] docs: Move kas-container usage into command line section

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

This makes it easier to find the usage of the tool and is more
consistent regarding the headlines we use.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---
docs/command-line.rst | 20 ++++++++++++++++++++
docs/userguide/kas-container-description.inc | 5 +++--
docs/userguide/kas-container.rst | 18 ------------------
3 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/docs/command-line.rst b/docs/command-line.rst
index fd25f16..fb5c9b8 100644
--- a/docs/command-line.rst
+++ b/docs/command-line.rst
@@ -7,6 +7,26 @@ Command Line Usage
:prog: kas
:nosubcommands:

+.. _kas-container-label:
+
+kas-container Usage
+-------------------
+
+.. kas-container-usage:: synopsis
+
+kas-container Commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. kas-container-usage:: commands
+
+Options
+~~~~~~~
+
+.. kas-container-usage:: options
+
+.. include:: userguide/aws-sso-warning.inc
+.. |AWS_CONFIG_SOURCE| replace:: ``--aws-dir ~/.aws``
+
.. _env-vars-label:

Environment Variables
diff --git a/docs/userguide/kas-container-description.inc b/docs/userguide/kas-container-description.inc
index 7762511..7789a5f 100644
--- a/docs/userguide/kas-container-description.inc
+++ b/docs/userguide/kas-container-description.inc
@@ -1,8 +1,9 @@
The ``kas-container`` script is a wrapper to run `kas` inside a build container.
It gives fine grained control over the data that is mapped into the build and
decouples the build environment from the host system. For details, see
-:ref:`env-vars-label`. The wrapper also takes care of mounting the necessary
-directories and setting up the environment variables inside the container.
+:ref:`kas-container-label` and :ref:`env-vars-label`. The wrapper also
+takes care of mounting the necessary directories and setting up the environment
+variables inside the container.

.. note::
The ``kas-container`` script has limited support for Git worktrees. Regular
diff --git a/docs/userguide/kas-container.rst b/docs/userguide/kas-container.rst
index b6b4095..d51ec82 100644
--- a/docs/userguide/kas-container.rst
+++ b/docs/userguide/kas-container.rst
@@ -2,21 +2,3 @@ Building in a Container
=======================

.. include:: kas-container-description.inc
-
-Synopsis
---------
-
-.. kas-container-usage:: synopsis
-
-kas-container Commands
-----------------------
-
-.. kas-container-usage:: commands
-
-Options
--------
-
-.. kas-container-usage:: options
-
-.. include:: aws-sso-warning.inc
-.. |AWS_CONFIG_SOURCE| replace:: ``--aws-dir ~/.aws``
--
2.47.3

[Jan Kiszka]

I just realized that we move the plugin command docs long ago over to
the User Guide section as well, and it would probably be tricky to
refactor those in a way that the options become part of "Command Line
Usage" again while some overview is still presented in the former
section. Now comes this moving proposal of mine here.

So, rather than trying to split, should we rather fold "Command Line
Usage" into the "User Guide", placing its sections where there fit and
do not hesitate to dive into command line options when plugins or
kas-container is presented?

Felix, you once split things up, but I guess I never fully understood
the implications. What do you think?

Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center

[MOESSBAUER, Felix]

I'm not against it. I once did the split to be able to create one
manpage per command (instead of a huge one).

Also for reading the docs, I prefer more pages with links instead of a
single big one. SPAs are IMHO a thing for tablets and phones, but I
don't think anybody is reading the kas CLI options on a phone.

>
> Felix, you once split things up, but I guess I never fully understood
> the implications. What do you think?

Give it a try. To me it anyways feels cleaner to have it as part of the
userguide. I'm also wondering if we should move the "Configuration
Format Changes" into the "Project Configuration" part, but we also
might have it more prominent.

Anyways, I mostly care about the manpages. As long as they are still
clean, everything is fine for me.

Felix

[Jan Kiszka]

Done in v3, and I like the result more.

Please also double-check the man pages, though they build fine for me.

[MOESSBAUER, Felix]

The html version now looks much cleaner and the manpages still look
fine.

Thanks for the cleanup!

Felix