From 6bc2627616871b1c4375949740c33d0989dbf321 Mon Sep 17 00:00:00 2001 From: Paul Barker Date: Fri, 6 Nov 2020 12:50:16 +0100 Subject: [PATCH] docs: Move command line details to a separate page This change makes the user guide page more readable and results in a command line usage page which is easy to navigate as all sub-commands can be found in the left-hand outline panel. Also fix the layout of the environment variables table by using a replacement. Signed-off-by: Paul Barker Signed-off-by: Jan Kiszka --- docs/command-line.rst | 69 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/userguide.rst | 66 ----------------------------------------- 3 files changed, 70 insertions(+), 66 deletions(-) create mode 100644 docs/command-line.rst diff --git a/docs/command-line.rst b/docs/command-line.rst new file mode 100644 index 0000000..a39eb87 --- /dev/null +++ b/docs/command-line.rst @@ -0,0 +1,69 @@ +Command line usage +================== + +.. argparse:: + :module: kas.kas + :func: kas_get_argparser + :prog: kas + + +Environment variables +--------------------- + ++-----------------------+-----------------------------------------------------+ +| Environment variables | Description | ++=======================+=====================================================+ +| ``KAS_WORK_DIR`` | The path of the kas work directory, current work | +| | directory is the default. | ++-----------------------+-----------------------------------------------------+ +| ``KAS_REPO_REF_DIR`` | The path to the repository reference directory. | +| | Repositories in this directory are used as | +| | references when cloning. In order for kas to find | +| | those repositories, they have to be named in a | +| | specific way. The repo URLs are translated like | +| | this: "https://github.com/siemens/meta-iot2000.git" | +| | resolves to the name | +| | "github.com.siemens.meta-iot2000.git". | ++-----------------------+-----------------------------------------------------+ +| ``KAS_DISTRO`` | This overwrites the respective setting in the | +| ``KAS_MACHINE`` | configuration file. | +| ``KAS_TARGET`` | | +| ``KAS_TASK`` | | ++-----------------------+-----------------------------------------------------+ +| ``KAS_PREMIRRORS`` | Specifies alternatives for repo URLs. Just like | +| | bitbake ``PREMIRRORS``, this variable consists of | +| | new-line separated entries. Each entry defines a | +| | regular expression to match a URL and, space- | +| | separated, its replacement. E.g.: | +| | "https://.*\.somehost\.io/ https://localmirror.net/"| ++-----------------------+-----------------------------------------------------+ +| ``SSH_PRIVATE_KEY`` | Path to the private key file that should be added | +| | to an internal ssh-agent. This key cannot be | +| | password protected. This setting is useful for CI | +| | build servers. On desktop machines, an ssh-agent | +| | running outside the kas environment is more useful. | ++-----------------------+-----------------------------------------------------+ +| ``SSH_AUTH_SOCK`` | SSH authentication socket. Used for cloning over | +| | SSH (alternative to ``SSH_PRIVATE_KEY``). | ++-----------------------+-----------------------------------------------------+ +| ``DL_DIR`` | Environment variables that are transferred to the | +| ``SSTATE_DIR`` | bitbake environment. | +| ``TMPDIR`` | | ++-----------------------+-----------------------------------------------------+ +| ``http_proxy`` | This overwrites the proxy configuration in the | +| ``https_proxy`` | configuration file. | +| ``ftp_proxy`` | | +| ``no_proxy`` | | ++-----------------------+-----------------------------------------------------+ +| ``GIT_PROXY_COMMAND`` | Set proxy for native git fetches. ``NO_PROXY`` is | +| ``NO_PROXY`` | evaluated by OpenEmbedded's oe-git-proxy script. | ++-----------------------+-----------------------------------------------------+ +| ``SHELL`` | The shell to start when using the `shell` plugin. | ++-----------------------+-----------------------------------------------------+ +| ``TERM`` | The terminal options used in the `shell` plugin. | ++-----------------------+-----------------------------------------------------+ +| ``AWS_CONFIG_FILE`` | Path to the awscli configuration and credentials | +| |aws_cred| | file that are copied to the kas home dir. | ++-----------------------+-----------------------------------------------------+ + +.. |aws_cred| replace:: ``AWS_SHARED_CREDENTIALS_FILE`` diff --git a/docs/index.rst b/docs/index.rst index c7e1615..1baba59 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,7 @@ Contents: intro userguide + command-line devguide format-changelog diff --git a/docs/userguide.rst b/docs/userguide.rst index 6127ac3..7550cf8 100644 --- a/docs/userguide.rst +++ b/docs/userguide.rst @@ -47,72 +47,6 @@ kas will place downloads and build artifacts under the current directory when being invoked. You can specify a different location via the environment variable `KAS_WORK_DIR`. -Command line usage -~~~~~~~~~~~~~~~~~~ - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - -Environment variables -~~~~~~~~~~~~~~~~~~~~~ - -+-----------------------+-----------------------------------------------------+ -| Environment variables | Description | -+=======================+=====================================================+ -| ``KAS_WORK_DIR`` | The path of the kas work directory, current work | -| | directory is the default. | -+-----------------------+-----------------------------------------------------+ -| ``KAS_REPO_REF_DIR`` | The path to the repository reference directory. | -| | Repositories in this directory are used as | -| | references when cloning. In order for kas to find | -| | those repositories, they have to be named in a | -| | specific way. The repo URLs are translated like | -| | this: "https://github.com/siemens/meta-iot2000.git" | -| | resolves to the name | -| | "github.com.siemens.meta-iot2000.git". | -+-----------------------+-----------------------------------------------------+ -| ``KAS_DISTRO`` | This overwrites the respective setting in the | -| ``KAS_MACHINE`` | configuration file. | -| ``KAS_TARGET`` | | -| ``KAS_TASK`` | | -+-----------------------+-----------------------------------------------------+ -| ``KAS_PREMIRRORS`` | Specifies alternatives for repo URLs. Just like | -| | bitbake ``PREMIRRORS``, this variable consists of | -| | new-line separated entries. Each entry defines a | -| | regular expression to match a URL and, space- | -| | separated, its replacement. E.g.: | -| | "https://.*\.somehost\.io/ https://localmirror.net/"| -+-----------------------+-----------------------------------------------------+ -| ``SSH_PRIVATE_KEY`` | Path to the private key file that should be added | -| | to an internal ssh-agent. This key cannot be | -| | password protected. This setting is useful for CI | -| | build servers. On desktop machines, an ssh-agent | -| | running outside the kas environment is more useful. | -+-----------------------+-----------------------------------------------------+ -| ``SSH_AUTH_SOCK`` | SSH authentication socket. Used for cloning over | -| | SSH (alternative to ``SSH_PRIVATE_KEY``). | -+-----------------------+-----------------------------------------------------+ -| ``DL_DIR`` | Environment variables that are transferred to the | -| ``SSTATE_DIR`` | bitbake environment. | -| ``TMPDIR`` | | -+-----------------------+-----------------------------------------------------+ -| ``http_proxy`` | This overwrites the proxy configuration in the | -| ``https_proxy`` | configuration file. | -| ``ftp_proxy`` | | -| ``no_proxy`` | | -+-----------------------+-----------------------------------------------------+ -| ``GIT_PROXY_COMMAND`` | Set proxy for native git fetches. ``NO_PROXY`` is | -| ``NO_PROXY`` | evaluated by OpenEmbedded's oe-git-proxy script. | -+-----------------------+-----------------------------------------------------+ -| ``SHELL`` | The shell to start when using the `shell` plugin. | -+-----------------------+-----------------------------------------------------+ -| ``TERM`` | The terminal options used in the `shell` plugin. | -+-----------------------+-----------------------------------------------------+ -| ``AWS_CONFIG_FILE`` | Path to the awscli configuration and credentials | -| ``AWS_SHARED_CREDENTIALS_FILE`` | file that are copied to the kas home dir. | -+-----------------------+-----------------------------------------------------+ Use Cases ---------