[Notes] [Git][BuildStream/buildstream][tiagogomes/docs-improvements] 4 c

Tiago Gomes pushed to branch tiagogomes/docs-improvements at BuildStream / buildstream

Commits:

5cdfac81

by Mathieu Bridon at 2018-09-28T09:20:20Z

data/userconfig.yaml: Document the cache.quota setting

5d3f039f

by Tom Pollard at 2018-09-28T10:34:13Z

Merge branch 'bochecha/cache-size' into 'master'

data/userconfig.yaml: Document the cache.quota setting

See merge request BuildStream/buildstream!833

fbcd2a27
by Tiago Gomes at 2018-09-28T10:38:55Z
```
doc: show an additional level on ToC
```

3225d10d

by Tiago Gomes at 2018-09-28T10:38:55Z

doc: updates considering website being live now

* Add a link to the website on the main page.
* Remove install instructions as they are now on the website.
* Remove Resources section as that information can be found at the
  website, and also looks bad.
* Move artifact server setup from the no longer existing Install section
  to the Using section.

11 changed files:

buildstream/data/userconfig.yaml
doc/source/index.rst
− doc/source/install_docker.rst
− doc/source/install_linux_distro.rst
− doc/source/install_source.rst
− doc/source/install_versions.rst
− doc/source/main_install.rst
doc/source/main_using.rst
− doc/source/release-badge.rst
− doc/source/snapshot-badge.rst
doc/source/install_artifacts.rst → doc/source/using_configuring_artifact_server.rst

Changes:

buildstream/data/userconfig.yaml

@@ -26,8 +26,13 @@ logdir: ${XDG_CACHE_HOME}/buildstream/logs
  #    Cache
+ #
  cache:
 -  # Size of the artifact cache - BuildStream will attempt to keep the
 +  # Size of the artifact cache in bytes - BuildStream will attempt to keep the
    # artifact cache within this size.
 +  # If the value is suffixed with K, M, G or T, the specified memory size is
 +  # parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base
 +  # 1024), respectively.
 +  # Alternatively, a percentage value may be specified, which is taken relative
 +  # to the isize of the file system containing the cache.
    quota: infinity
+ #

doc/source/index.rst

@@ -13,20 +13,14 @@ They begin with a basic introduction to BuildStream, background
  information on basic concepts, and a guide to the BuildStream command line interface.
  Later sections provide detailed information on BuildStream internals.
 +If you are looking for information about how to install BuildStream,
 +please refer to the `BuildStream website <https://buildstream.build>`_.
  .. toctree::
 -   :maxdepth: 1
 +   :maxdepth: 2
     main_about
 -   main_install
     main_using
     main_core
     CONTRIBUTING
+-
 -Resources
 ----------
 -* GitLab repository: https://gitlab.com/BuildStream/buildstream
 -* Bug Tracking: https://gitlab.com/BuildStream/buildstream/issues
 -* Mailing list: https://mail.gnome.org/mailman/listinfo/buildstream-list
 -* IRC Channel: irc://irc.gnome.org/#buildstream

doc/source/install_docker.rst deleted

+-
+-
 -.. _docker:
+-
 -BuildStream inside Docker
 --------------------------
 -If your system cannot provide the base system requirements for BuildStream, then it is possible to run buildstream within a Docker image.
+-
 -The BuildStream project provides
 -`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora>`_
 -containing BuildStream and its dependencies.
 -This gives you an easy way to get started using BuildStream on any Unix-like
 -platform where Docker is available, including Mac OS X.
+-
 -We recommend using the
 -`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_
 -which automates the necessary container setup. You can download it and make
 -it executable like this:
+-
 -.. code:: bash
+-
 -  mkdir -p ~/.local/bin
 -  curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-here > ~/.local/bin/bst-here
 -  chmod +x ~/.local/bin/bst-here
+-
 -Check if ``~/.local/bin`` appears in your PATH environment variable -- if it
 -doesn't, you should
 -`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_.
+-
 -Once the script is available in your PATH, you can run ``bst-here`` to open a
 -shell session inside a new container based off the latest version of the
 -buildstream-fedora Docker image. The current working directory will be mounted
 -inside the container at ``/src``.
+-
 -You can also run individual BuildStream commands as ``bst-here COMMAND``. For
 -example: ``bst-here show systems/my-system.bst``. Note that BuildStream won't
 -be able to integrate with Bash tab-completion if you invoke it in this way.
+-
 -Two Docker volumes are set up by the ``bst-here`` script:
+-
 - * ``buildstream-cache --`` mounted at ``~/.cache/buildstream``
 - * ``buildstream-config --`` mounted at ``~/.config/``
+-
 -These are necessary so that your BuildStream cache and configuration files
 -persist between invocations of ``bst-here``.

doc/source/install_linux_distro.rst deleted

+-
+-
 -.. _install_linux_distro:
+-
 -Installing from distro packages
 -===============================
 -BuildStream is available on some linux distributions, here are
 -some install instructions for the linux distributions which
 -have packaged BuildStream.
+-
+-
 -Arch Linux
 -----------
 -Packages for Arch exist in `AUR <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
 -Two different package versions are available:
+-
 -* Latest release: `buildstream <https://aur.archlinux.org/packages/buildstream>`_
 -* Latest development snapshot: `buildstream-git <https://aur.archlinux.org/packages/buildstream-git>`_
+-
+-
 -Fedora
 -------
 -BuildStream is not yet in the official Fedora repositories, but you can
 -install it from a Copr::
+-
 -  sudo dnf copr enable bochecha/buildstream
 -  sudo dnf install buildstream
+-
 -Optionally, install the ``buildstream-docs`` package to have the BuildStream
 -documentation in Devhelp or GNOME Builder.

doc/source/install_source.rst deleted

+-
+-
 -Installing from source
 -======================
 -Until BuildStream is available in :ref:`your distro <install_linux_distro>`, you will
 -need to install it yourself from source.
+-
+-
 -Installing dependencies
 ------------------------
 -Before installing BuildStream from source, it is necessary to first install
 -the system dependencies. Below are some linux distribution specific instructions
 -for installing these dependencies.
+-
 -BuildStream requires the following base system requirements:
+-
 -* python3 >= 3.5
 -* bubblewrap >= 0.1.2
 -* fuse2
+-
 -BuildStream also depends on the host tools for the :mod:`Source <buildstream.source>` plugins.
 -Refer to the respective :ref:`source plugin <plugins_sources>` documentation for host tool
 -requirements of specific plugins.
+-
 -The default plugins with extra host dependencies are:
+-
 -* bzr
 -* deb
 -* git
 -* ostree
 -* patch
 -* pip
 -* tar
+-
 -If you intend to push built artifacts to a remote artifact server,
 -which requires special permissions, you will also need:
+-
 -* ssh
+-
+-
 -Arch Linux
 -~~~~~~~~~~
 -Install the dependencies with::
+-
 -  sudo pacman -S \
 -      python fuse2 bubblewrap \
 -      python-pip
+-
 -For the default plugins::
+-
 -  sudo pacman -S \
 -      bzr git lzip ostree patch python-gobject
+-
+-
 -The package *python-arpy* is required by the deb source plugin. This is not
 -obtainable via `pacman`, you must get *python-arpy* from AUR:
 -https://aur.archlinux.org/packages/python-arpy/
+-
 -To install::
+-
 -  wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-arpy.tar.gz
 -  tar -xvf python-arpy.tar.gz
 -  cd python-arpy
 -  makepkg -si
+-
+-
 -Debian
 -~~~~~~
 -Install the dependencies with::
+-
 -  sudo apt-get install \
 -      python3 fuse bubblewrap \
 -      python3-pip python3-dev
+-
 -For the default plugins:
+-
+-
 -Stretch
 -+++++++
 -With stretch, you first need to ensure that you have the backports repository
 -setup as described `here <https://backports.debian.org/Instructions/>`_
+-
 -By adding the following line to your sources.list::
+-
 -  deb http://deb.debian.org/debian stretch-backports main
+-
 -And then running::
+-
 -  sudo apt update
+-
 -At this point you should be able to get the system requirements for the default plugins with::
+-
 -  sudo apt install \
 -      bzr git lzip patch python3-arpy python3-gi
 -  sudo apt install -t stretch-backports \
 -      gir1.2-ostree-1.0 ostree
+-
+-
 -Buster or Sid
 -+++++++++++++
 -For debian unstable or testing, only the following line should be enough
 -to get the system requirements for the default plugins installed::
+-
 -  sudo apt-get install \
 -      lzip gir1.2-ostree-1.0 git bzr ostree patch python3-arpy python3-gi
+-
+-
 -Fedora
 -~~~~~~
 -For recent fedora systems, the following line should get you the system
 -requirements you need::
+-
 -  dnf install -y \
 -      python3 fuse bubblewrap \
 -      python3-pip python3-devel
+-
 -For the default plugins::
+-
 -  dnf install -y \
 -      bzr git lzip patch ostree python3-gobject
 -  pip3 install --user arpy
+-
+-
 -Ubuntu
 -~~~~~~
+-
+-
 -Ubuntu 18.04 LTS or later
 -+++++++++++++++++++++++++
 -Install the dependencies with::
+-
 -  sudo apt install \
 -      python3 fuse bubblewrap \
 -      python3-pip python3-dev
+-
 -For the default plugins::
+-
 -  sudo apt install \
 -      bzr gir1.2-ostree-1.0 git lzip ostree patch python3-arpy python3-gi
+-
+-
 -Ubuntu 16.04 LTS
 -++++++++++++++++
 -On Ubuntu 16.04, neither `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_
 -or `ostree <https://github.com/ostreedev/ostree>`_ are available in the official repositories.
 -You will need to install them in whichever way you see fit. Refer the the upstream documentation
 -for advice on this.
+-
+-
 -Installing
 -----------
 -Once you have the base system dependencies, you can install the BuildStream
 -python package as a regular user.
+-
+-
 -Installing from PyPI (recommended)
 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -Since we only ever publish :ref:`release versions <install_semantic_versioning>` on
 -PyPI, it is currently recommended to use this installation path. This will
 -ensure that you always have the latest recommended version of BuildStream that
 -we recommend.
+-
 -To install from PyPI, you will additionally require:
+-
 -* pip for python3 (only required for setup)
 -* Python 3 development libraries and headers
+-
 -Simply run the following command::
+-
 -  pip3 install --user BuildStream
+-
 -This will install latest stable version of BuildStream and its pure python
 -dependencies into your user's homedir in ``~/.local``.
+-
 -Keep following the instructions below to ensure that the ``bst``
 -command is in your ``PATH`` and to enable bash completions for it.
+-
 -.. note::
+-
 -  If you want a specific version of BuildStream, you can install it using
 -  ``pip install --user BuildStream==<version-number>``
+-
+-
 -Upgrading from PyPI
 -+++++++++++++++++++
 -Once you have already installed BuildStream from PyPI, you can later update
 -to the latest recommended version like so::
+-
 -  pip install --user --upgrade BuildStream
+-
+-
 -.. _install_git_checkout:
+-
 -Installing from a git checkout
 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -To install directly from the `git repository <https://gitlab.com/BuildStream/buildstream.git>`_
 -using python's ``pip`` package manager, you will additionally require:
+-
 -* pip for python3 (only required for setup)
 -* Python 3 development libraries and headers
 -* git (to checkout BuildStream)
+-
 -Before installing, please check the existing tags in the git repository
 -and determine which version you want to install, and whether you want
 -to install an official release version (recommended), or a development snapshot
 -to help us out testing the bleeding edge of development. Follow the
 -:ref:`semantic versioning guide <install_semantic_versioning>` to determine
 -which tag you intend to install.
+-
 -Run the following commands::
+-
 -  git clone https://gitlab.com/BuildStream/buildstream.git
 -  cd buildstream
 -  git checkout <desired release tag>
 -  pip3 install --user -e .
+-
 -This will install buildstream's pure python dependencies into
 -your user's homedir in ``~/.local`` and will run BuildStream directly
 -from the git checkout directory.
+-
 -Keep following the instructions below to ensure that the ``bst``
 -command is in your ``PATH`` and to enable bash completions for it.
+-
 -.. note::
+-
 -   We recommend the ``-e`` option because you can upgrade your
 -   installation by simply updating the checked out git repository.
+-
 -   If you want a full installation that is not linked to your
 -   git checkout, just omit the ``-e`` option from the above commands.
+-
+-
 -Upgrading from a git checkout
 -+++++++++++++++++++++++++++++
 -If you installed BuildStream from a local git checkout using ``-e`` option, all
 -you need to do to upgrade BuildStream is to update your local git checkout::
+-
 -  cd /path/to/buildstream
 -  git pull --rebase
+-
 -If you did not specify the ``-e`` option at install time or the dependancies
 -have changed, you will need to cleanly reinstall BuildStream::
+-
 -  pip3 uninstall buildstream
 -  cd /path/to/buildstream
 -  git pull --rebase
 -  pip3 install --user .
+-
 -.. note::
+-
 -   If BuildStream has added any dependencies since the last upgrade,
 -   you will need to uninstall and reinstall to ensure those dependencies
 -   are met, regardless of whether you have used the ``-e`` option at
 -   install time.
+-
+-
 -Post install setup
 -------------------
 -After having installed from source using any of the above methods, some
 -setup will be required to use BuildStream.
+-
+-
 -Adjust PATH
 -~~~~~~~~~~~
 -Since BuildStream is now installed under your local user's install directories,
 -you need to ensure that ``PATH`` is adjusted.
+-
 -A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
+-
 -  export PATH="${PATH}:${HOME}/.local/bin"
+-
 -.. note::
+-
 -   You will have to restart your terminal in order for these changes to take effect.
+-
+-
 -Bash completions
 -~~~~~~~~~~~~~~~~
 -Bash completions are supported by sourcing the ``buildstream/data/bst``
 -script found in the BuildStream repository. On many systems this script
 -can be installed into a completions directory but when installing BuildStream
 -without a package manager this is not an option.
+-
 -To enable completions for an installation of BuildStream you
 -installed yourself from git, just append the script verbatim
 -to your ``~/.bash_completion``:
+-
 -.. literalinclude:: ../../buildstream/data/bst
 -   :language: yaml

doc/source/install_versions.rst deleted

+-
+-
 -.. _install_semantic_versioning:
+-
 -Semantic Versioning
 -===================
 -BuildStream follows the Semantic Versioning Convention `(SemVer) <https://semver.org/>`_,
 -and uses even minor point numbers to denote releases intended for users while
 -odd minor point numbers represent development snapshops.
+-
 -For example, for a given version number ``X.Y.Z``
 - * The ``X.<even number>.*`` versions are releases intended for users.
 - * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
+-
 -If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
 -tag to ensure you're getting the latest release.
+-
 -* Latest release:
+-
 -  .. include:: release-badge.rst
+-
 -* Latest development snapshot:
+-
 -  .. include:: snapshot-badge.rst

doc/source/main_install.rst deleted

+-
+-
 -.. _install:
+-
 -Install
 -=======
+-
 -.. include:: release-badge.rst
+-
 -.. include:: snapshot-badge.rst
+-
 -This section provides instructions for installing BuildStream and its
 -companion artifact server on various platforms, along with any installation
 -related materials.
+-
 -.. note::
+-
 -   BuildStream is currently only supported natively on Linux. Users of Unix-like
 -   systems where Docker is available can still use BuildStream by following the
 -   :ref:`Docker install guide <docker>`
+-
 -.. toctree::
 -   :maxdepth: 1
+-
 -   install_source
 -   install_linux_distro
 -   install_docker
 -   install_artifacts
 -   install_versions

doc/source/main_using.rst

@@ -15,3 +15,4 @@ guides and information on user preferences and configuration.
     using_examples
     using_config
     using_commands
 +   using_configuring_artifact_server

doc/source/release-badge.rst deleted

+-
 -.. Use this file to include the badge in the documentation, but not in
 -   the README.rst or gitlab rendered materials, that doesnt work.
+-
 -   This is partly a workaround for a sphinx issue, we will be able
 -   to avoid the raw html once this is implemented in sphinx:
+-
 -       https://github.com/sphinx-doc/sphinx/issues/2240
+-
 -   Using the <object> tag instead of the <img> tag which sphinx generates
 -   allows the svg to be "interactive", for us this basically means that
 -   the link we encode in the badge svg is used, rather than static urls
 -   which need to be used around the <img> tag.
+-
 -   WARNING: The custom CSS on the style tag will need to change if we
 -            change the theme, so that the <object> tag behaves similar
 -	    to how the <img> tag is themed by the style sheets.
+-
 -.. raw:: html
+-
 -   <a class="reference external image-reference">
 -     <object style="margin-bottom:24px;vertical-align:middle"
 -             data=""
 -	     type="image/svg+xml"/>
 -     </object>
 -   </a>

doc/source/snapshot-badge.rst deleted

+-
 -.. Use this file to include the badge in the documentation, but not in
 -   the README.rst or gitlab rendered materials, that doesnt work.
+-
 -   This is partly a workaround for a sphinx issue, we will be able
 -   to avoid the raw html once this is implemented in sphinx:
+-
 -       https://github.com/sphinx-doc/sphinx/issues/2240
+-
 -   Using the <object> tag instead of the <img> tag which sphinx generates
 -   allows the svg to be "interactive", for us this basically means that
 -   the link we encode in the badge svg is used, rather than static urls
 -   which need to be used around the <img> tag.
+-
 -   WARNING: The custom CSS on the style tag will need to change if we
 -            change the theme, so that the <object> tag behaves similar
 -	    to how the <img> tag is themed by the style sheets.
+-
 -.. raw:: html
+-
 -   <a class="reference external image-reference">
 -     <object style="margin-bottom:24px;vertical-align:middle"
 -             data=""
 -	     type="image/svg+xml"/>
 -     </object>
 -   </a>

doc/source/install_artifacts.rst → doc/source/using_configuring_artifact_server.rst

@@ -2,8 +2,8 @@
  .. _artifacts:
 -Installing an artifact server
 -=============================
 +Configuring Artifact Server
 +===========================
  BuildStream caches the results of builds in a local artifact cache, and will
  avoid building an element if there is a suitable build already present in the
  local artifact cache.
@@ -72,7 +72,7 @@ Installing the server
  ~~~~~~~~~~~~~~~~~~~~~
  You will also need to install BuildStream on the artifact server in order
  to receive uploaded artifacts over ssh. Follow the instructions for installing
 -BuildStream :ref:`here <install>`
 +BuildStream `here <https://buildstream.build/install.html>`_.
  When installing BuildStream on the artifact server, it must be installed
  in a system wide location, with ``pip3 install .`` in the BuildStream

[Notes] [Git][BuildStream/buildstream][tiagogomes/docs-improvements] 4 commits: data/userconfig.yaml: Document the cache.quota setting

Tiago Gomes pushed to branch tiagogomes/docs-improvements at BuildStream / buildstream

Commits:

11 changed files:

Changes: