From 35a79363a4e9c6521c4f349b97a505c4b2ebba7c Mon Sep 17 00:00:00 2001 From: Prawn Date: Fri, 24 Jun 2022 01:43:34 +0000 Subject: [PATCH] docs: add sphinx docs and gitlab pages --- .gitlab-ci.yml | 24 ++++ docs/.gitignore | 4 + docs/Makefile | 16 +++ docs/requirements.txt | 3 + docs/source/cli.rst | 17 +++ docs/source/cmd.rst | 21 +++ docs/source/conf.py | 21 +++ docs/source/config.rst | 129 ++++++++++++++++++ docs/source/index.rst | 16 +++ docs/source/install.rst | 35 +++++ .../static/kupfer-black-transparent.svg | 90 ++++++++++++ docs/source/static/kupfer-white-filled.svg | 90 ++++++++++++ .../static/kupfer-white-transparent.svg | 90 ++++++++++++ docs/source/static/kupfer_docs.css | 3 + docs/source/templates/command.rst | 5 + 15 files changed, 564 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/requirements.txt create mode 100644 docs/source/cli.rst create mode 100644 docs/source/cmd.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/config.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/install.rst create mode 100644 docs/source/static/kupfer-black-transparent.svg create mode 100644 docs/source/static/kupfer-white-filled.svg create mode 100644 docs/source/static/kupfer-white-transparent.svg create mode 100644 docs/source/static/kupfer_docs.css create mode 100644 docs/source/templates/command.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index fd1fb9d..fab49eb 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,6 +1,7 @@ stages: - check - build + - deploy format: stage: check @@ -34,3 +35,26 @@ build_docker: only: - main - dev + +.docs: + image: "${CI_REGISTRY_IMAGE}:dev" + before_script: + - pacman -Sy --noconfirm python-sphinx-{click,furo} + script: + - (cd docs && make) + - mv docs/html public + artifacts: + paths: + - public + +build_docs: + stage: build + extends: .docs + except: + - dev + +pages: + stage: deploy + extends: .docs + only: + - dev diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..35bacdd --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,4 @@ +.buildinfo +.doctrees +html +source/cli diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..3cccb8e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,16 @@ +buildargs := -b dirhtml -aE source html + +.PHONY: cleanbuild clean + +cleanbuild: + @make clean + @make html + +clean: + rm -rf html source/cli + +html: + sphinx-build $(buildargs) + +serve: html + (cd html && python -m http.server 9999) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..372f33b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx-click +# furo sphinx theme +furo diff --git a/docs/source/cli.rst b/docs/source/cli.rst new file mode 100644 index 0000000..b848f6e --- /dev/null +++ b/docs/source/cli.rst @@ -0,0 +1,17 @@ +############# +CLI Interface +############# + +.. click:: main:cli + :nested: none + :prog: kupferbootstrap + + +Commands +======== + +.. generated by cmd.rst +.. toctree:: + :glob: + + cli/* diff --git a/docs/source/cmd.rst b/docs/source/cmd.rst new file mode 100644 index 0000000..dd61c17 --- /dev/null +++ b/docs/source/cmd.rst @@ -0,0 +1,21 @@ +:orphan: +:nosearch: + +only used to trigger builds of the submodule docs! + +.. autosummary:: + :toctree: cli + :template: command.rst + :recursive: + + boot + cache + chroot + config + flash + forwarding + image + packages + ssh + telnet + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..cedacc7 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,21 @@ +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +extensions = [ + 'sphinx_click', + 'sphinx.ext.autosummary', # Create neat summary tables +] +templates_path = ['templates'] +project = 'Kupfer👢strap' +html_title = 'Kupferbootstrap' +html_theme = 'furo' +html_static_path = ['static'] +html_css_files = ['kupfer_docs.css'] +html_favicon = 'static/kupfer-white-filled.svg' +html_theme_options = { + "globaltoc_maxdepth": 5, + "globaltoc_collapse": True, + "light_logo": "kupfer-black-transparent.svg", + "dark_logo": "kupfer-white-transparent.svg", +} diff --git a/docs/source/config.rst b/docs/source/config.rst new file mode 100644 index 0000000..8292a64 --- /dev/null +++ b/docs/source/config.rst @@ -0,0 +1,129 @@ +############# +Configuration +############# + + +Kupferbootstrap uses `toml `_ for its configuration file. + +The file can either be edited manually or managed via the :doc:`cli/config` subcommand. + +You can quickly generate a default config by running :code:`kupferbootstrap config init -N`. + + +File Location +############# + +The configuration is stored in ``~/.config/kupfer/kupferbootstrap.toml``, where ``~`` is your user's home folder. + + +Sections +######## + +A config file is split into sections like so: + +.. code-block:: toml + + [pkgbuilds] + git_repo = "https://gitlab.com/kupfer/packages/pkgbuilds.git" + git_branch = "dev" + + [pacman] + parallel_downloads = 3 + + +Here, we have two sections: ``pkgbuilds`` and ``pacman``. + +Flavours +######## + +Flavours are preset collections of software and functionality to enable, +i.e. desktop environments like `Gnome `_ +and `Phosh `_. + + +Profiles +######## + +The last section and currently the only one with subsections is the ``profiles`` section. + +A profile is the configuration of a specific device image. It specifies (amongst others): + +* the device model +* the flavour (desktop environment) +* the host- and user name +* extra packages to install + +Using a profile's ``parent`` key, +you can inherit settings from another profile. + +This allows you to easily keep a number of slight variations of the same target profile around +without the need to constantly modify your Kupferbootstrap configuration file. + +You can easily create new profiles with +`kupferbootstrap config profile init <../cli/config/#kupferbootstrap-config-profile-init>`_. + +Here's an example: + +.. code:: toml + + [profiles] + current = "graphical" + + [profiles.default] + parent = "" + device = "oneplus-enchilada" + flavour = "phosh" + pkgs_include = [ "wget", "rsync", "nano", "tmux", "zsh", "pv", ] + pkgs_exclude = [] + hostname = "kupferphone" + username = "prawn" + size_extra_mb = 800 + + [profiles.graphical] + parent = "default" + pkgs_include = [ "firefox", "tilix", "gnome-tweaks" ] + size_extra_mb = "+3000" + + [profiles.hades] + parent = "graphical" + flavour = "phosh" + hostname = "hades" + + [profiles.recovery] + parent = "default" + flavour = "debug-shell" + + [profiles.beryllium] + parent = "graphical" + device = "xiaomi-beryllium-ebbg" + flavour = "gnome" + hostname = "pocof1" + + + +The ``current`` key in the ``profiles`` section controlls which profile gets used by Kupferbootstrap by default. + +The first subsection (``profiles.default``) describes the `default` profile +which gets created by `config init <../cli/config/#kupferbootstrap-config-init>`_. + +Next, we have a `graphical` profile that defines a couple of graphical programs for all but the `recovery` profile, +since that doesn't have a GUI. + +``size_extra_mb`` +----------------- + +Note how ``size_extra_mb`` can either be a plain integer (``800``) or a string, +optionally leading with a plus sign (``+3000``), +which instructs Kupferbootstrap to add the value to the parent profile's ``size_extra_mb``. + +``pkgs_include`` / ``pkgs_exclude`` +----------------------------------- + +Like ``size_extra_mb``, ``pkgs_include`` will be merged with the parent profile's ``pkgs_include``. + +To exclude unwanted packages from being inherited from a parent profile, use ``pkgs_exclude`` in the child profile. + +.. hint:: + ``pkgs_exclude`` has no influence on Pacman's dependency resolution. + It only blocks packages during image build that would usually be explicitly installed + due to being listed in a parent profile or the selected flavour. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..44c3f96 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,16 @@ +############################# +Kupferbootstrap Documentation +############################# + +This is the documentation for `Kupferbootstrap `_, +a tool to build and flash packages and images for the `Kupfer `_ mobile Linux distro. + + +Documentation pages +=================== + +.. toctree:: + + install + config + cli diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..4620758 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,35 @@ +############ +Installation +############ + + +#. + Install Python 3, Docker, and git. + + On Arch: ``pacman -S python docker git --needed --noconfirm`` + + .. Hint:: + After installing Docker you will have to add your user to the ``docker`` group: + + ``sudo usermod -aG docker "$(whoami)"`` + + Then restart your desktop session for the new group to take effect. + +#. Pick which Kupferbootstrap branch to clone: usually either ``main`` or ``dev`` + +#. Clone the repository: ``git clone -b INSERT_BRANCHNAME_HERE https://gitlab.com/kupfer/kupferbootstrap`` + +#. Change into the folder: ``cd kupferbootstrap`` + +#. + Install python dependencies: ``pip3 install -r requirements.txt`` + + .. Note:: + Most of our python dependencies are available as distro packages on most distros, + sadly it's incomplete on Arch. + + See ``requirements.txt`` for the list of required python packages. + +#. Symlink ``kupferbootstrap`` into your ``$PATH``: ``sudo ln -s "$(pwd)/bin/kupferbootstrap" /usr/local/bin/`` + +#. You should now be able to run ``kupferbootstrap --help``! diff --git a/docs/source/static/kupfer-black-transparent.svg b/docs/source/static/kupfer-black-transparent.svg new file mode 100644 index 0000000..2b94f78 --- /dev/null +++ b/docs/source/static/kupfer-black-transparent.svg @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + Cu + 29 + 63.546 + + diff --git a/docs/source/static/kupfer-white-filled.svg b/docs/source/static/kupfer-white-filled.svg new file mode 100644 index 0000000..da92521 --- /dev/null +++ b/docs/source/static/kupfer-white-filled.svg @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + + + Cu + 29 + 63.546 + + diff --git a/docs/source/static/kupfer-white-transparent.svg b/docs/source/static/kupfer-white-transparent.svg new file mode 100644 index 0000000..65d5a4a --- /dev/null +++ b/docs/source/static/kupfer-white-transparent.svg @@ -0,0 +1,90 @@ + + + + + + + + + + + + + + + + Cu + 29 + 63.546 + + diff --git a/docs/source/static/kupfer_docs.css b/docs/source/static/kupfer_docs.css new file mode 100644 index 0000000..b89050c --- /dev/null +++ b/docs/source/static/kupfer_docs.css @@ -0,0 +1,3 @@ +.sidebar-brand-text { + text-align: center; +} diff --git a/docs/source/templates/command.rst b/docs/source/templates/command.rst new file mode 100644 index 0000000..8345d09 --- /dev/null +++ b/docs/source/templates/command.rst @@ -0,0 +1,5 @@ +.. title: {{fullname}} + +.. click:: {% if fullname == 'main' %}main:cli{% else %}{{fullname}}:cmd_{{fullname}}{% endif %} + :prog: kupferbootstrap {{fullname}} + :nested: full