Commit 72bbaaae authored by Vasilis Tsiligiannis's avatar Vasilis Tsiligiannis
Browse files

Add basic documentation

Signed-off-by: Vasilis Tsiligiannis's avatarVasilis Tsiligiannis <>
parent 419329d8
# Minimal makefile for Sphinx documentation
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXBUILD ?= sphinx-build
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
# Configuration file for the Sphinx documentation builder.
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import satnogsconfig
# -- Project information -----------------------------------------------------
project = 'SatNOGS Config'
copyright = '2020, Libre Space Foundatio'
author = 'SatNOGS'
version = satnogsconfig.__version__
release = satnogsconfig.__version__
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
Developer guide
To install SatNOGS Config for development run in the project root directory::
$ pip install -e .
This project uses ``python-dotenv``.
Configuration of ``satnogsconfig/`` can be overridden by setting the respective environment variables or an ``.env`` file placed on the project root directory.
SatNOGS Config functionality can be extended by implementing additional helpers.
The helpers are used to enhance menu functionality beyond the core function of generating a YAML file for Ansible.
Modifying the menu
The menu itself is also expressed in YAML format.
The menu structure is defined in ``menu.yml`` file and shipped along with the package.
Code Quality Assurance
The following code quality assurance tools are used in this project:
* ``flake8``
* ``isort``
* ``yapf``
* ``pylint``
``tox`` is used to automate development tasks.
To execute the default list of tasks run::
$ tox
SatNOGS Config utility
SatNOGS Config is a utility for generating the configuration for a Debian-based SatNOGS client system.
It is a menu driven configuration tool built on-top of ``pythondialog``.
The main purpose of this utility is to create the YAML configuration file for SatNOGS Client Ansible which provisions the system.
In addition to that, it interacts with ``satnogs-setup``, which is a wrapper to bootstrap Ansible, upgrades the system packages using APT and probes the hardware to show the user a more limited set of configuration options.
Table of Contents
.. toctree::
:maxdepth: 4
Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Modules reference
.. automodule:: satnogsconfig
.. automodule:: satnogsconfig.config
.. automodule:: satnogsconfig.helpers
.. automodule::
.. automodule:: satnogsconfig.settings
User guide
To install SatNOGS Config run::
$ pip install satnogs-config
This will install a console script called ``satnogs-config``.
To execute the script, run it on the command line::
$ satnogs-config
The main menu will be shown
The ``Basic`` sub-menu contains the minimum required configuration options for provisioning the SatNOGS client system.
The ``Advanced`` sub-menu contains a larger set of configuration options.
It is intended for advanced users and contains options categorized by component.
The ``Show`` option displays the current configuration file.
The ``Upgrade`` option calls ``APT`` utilities to upgrade the distribution packages.
The ``Update`` option works in conjunction with ``satnogs-setup`` to re-bootstrap Ansible and update the configuration tools.
The ``Reset`` option resets the configuration file generated by the utility, effectively removing all the configuration options set by the user.
The ``Apply`` option runs SatNOGS Client Ansible which provisions Debian to become a SatNOGS client system.
......@@ -6,6 +6,7 @@ flake8 = 3.7.9
isort = 4.3.21
yapf = 0.29.0
pylint = 2.4.4
sphinx_rtd_theme = 0.4.3
deps =
......@@ -44,3 +45,10 @@ commands = pylint {envsitepackagesdir}/satnogsconfig
skip_install = True
commands =
python sdist bdist_wheel
deps =
changedir = {toxinidir}/docs
commands =
{envbindir}/sphinx-build -b html . "_build/html"
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment