Added documentation for: https://python-archinstall.readthedocs.io/en/latest/

9 files changed, 405 insertions, 0 deletions

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..d4bb2cbb
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.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
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
new file mode 100644
index 00000000..ac3ed4e8
--- /dev/null
+++ b/docs/_static/logo.png
diff --git a/docs/archinstall/Installer.rst b/docs/archinstall/Installer.rst
new file mode 100644
index 00000000..b7d8c8ce
--- /dev/null
+++ b/docs/archinstall/Installer.rst
@@ -0,0 +1,11 @@
+.. _archinstall.Installer:
+
+Installer
+=========
+
+The installer is the main class for accessing a installation-instance.
+You can look at this class as the installation you have or will perform.
+
+Anything related to **inside** the installation, will be found in this class.
+
+.. autofunction:: archinstall.Installer
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000..63e08e8a
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,129 @@
+import sys, os
+sys.path.insert(0, os.path.abspath('..'))
+
+import re
+
+def process_docstring(app, what, name, obj, options, lines):
+    spaces_pat = re.compile(r"( {8})")
+    ll = []
+    for l in lines:
+        ll.append(spaces_pat.sub("    ",l))
+    lines[:] = ll
+
+def setup(app):
+    app.connect('autodoc-process-docstring', process_docstring)
+
+# 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:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- 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('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'python-archinstall'
+copyright = '2020, Anton Hvornum'
+author = 'Anton Hvornum'
+
+# The full version, including alpha/beta/rc tags
+release = 'v2.0.4'
+
+
+# -- General configuration ---------------------------------------------------
+
+master_doc = 'index'
+# 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.inheritance_diagram',
+	'sphinx.ext.todo'
+]
+
+# 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 = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+html_logo = "_static/logo.png"
+
+# 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']
+
+# If false, no module index is generated.
+html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+html_split_index = True
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'slimhttpdoc'
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'archinstall', u'archinstall Documentation',
+     [u'Anton Hvornum'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'archinstall', u'archinstall Documentation',
+   u'Anton Hvornum', 'archinstall', 'Simple and minimal HTTP server.'),
+]
diff --git a/docs/examples/binary.rst b/docs/examples/binary.rst
new file mode 100644
index 00000000..7b25e201
--- /dev/null
+++ b/docs/examples/binary.rst
@@ -0,0 +1,23 @@
+.. _examples.python:
+
+Binary executable
+=================
+
+.. warning:: The binary option is limited and stiff. It's hard to modify or create your own installer-scripts this way unless you compile the source manually. If your usecase needs custom scripts, either use the pypi setup method or you'll need to adjust the PKGBUILD prior to building the arch package.
+
+The binary executable is a standalone compiled version of the library.
+It's compiled using `nuitka <https://nuitka.net/>`_ with the flag `--standalone`.
+
+Executing the binary
+--------------------
+
+As an example we'll use the `guided <https://github.com/Torxed/archinstall/blob/master/examples/guided.py>`_ installer.
+To run the `guided` installed, all you have to do *(after installing or compiling the binary)*, is run:
+
+
+.. code-block::
+
+    ./archinstall guided
+
+As mentioned, the binary is a bit rudimentary and only supports executing whatever is found directly under `./archinstall/examples`.
+Anything else won't be found. This is subject to change in the future to make it a bit more flexible.
\ No newline at end of file
diff --git a/docs/examples/python.rst b/docs/examples/python.rst
new file mode 100644
index 00000000..ca0de708
--- /dev/null
+++ b/docs/examples/python.rst
@@ -0,0 +1,59 @@
+.. _examples.python:
+
+Python module
+=============
+
+Archinstall supports running in `module mode <https://docs.python.org/3/library/__main__.html>`_.
+The way the library is invoked in module mode is limited to executing scripts under the **example** folder.
+
+It's there for important to place any script or profile you wish to invoke in the examples folder prior to building and installing.
+
+Pre-requisits
+-------------
+
+We'll assume you've followed the `installing.python.manual`_ method.
+Before actually installing the library, you will need to place your custom installer-scripts under `./archinstall/examples/` as a python file.
+
+More on how you create these in the next section.
+
+.. warning::
+
+    This is subject to change in the future as this method is currently a bit stiff. The script path will become a parameter. But for now, this is by design.
+
+Creating a script
+-----------------
+
+Lets create a `test_installer` - installer as an example. This is assuming that the folder `./archinstall` is a git-clone of the main repo.
+We begin by creating `./archinstall/examples/test_installer.py`. The placement here is important later.
+
+This script can now already be called using `python -m archinstall test_installer` after a successful installation of the library itself.
+But the script won't do much. So we'll do something simple like list all the harddrives as an example.
+
+To do this, we'll begin by importing `archinstall` in our `./archinstall/examples/test_installer.py` and call some functions.
+
+.. code-block:: python
+
+    import archinstall
+    
+    all_drives = archinstall.list_drives()
+    print(all_drives)
+
+This should print out a list of drives and some meta-information about them.
+As an example, this will do just fine.
+
+Now, go ahead and install the library either as a user-module or system-wide.
+
+Calling a module
+----------------
+
+Assuming you've followed the example in `Creating a script`_, you can now safely call it with:
+
+.. code-block::
+
+    python -m archinstall test_installer
+
+This should now print all available drives on your system.
+
+.. note::
+
+    This should work on any system, not just Arch Linux based ones. But note that other functions in the library relies heavily on Arch Linux based commands to execute the installation steps. Such as `arch-chroot`.
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..627347e9
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,51 @@
+python-archinstall Documentation
+================================
+
+| **python-archinstall** *(or, archinstall for short)* is a helper library to install Arch Linux and manage services, packages and other things.
+| It comes packaged with different installers *(shopped as scripts)*, such as _guided and _automated installer that can be run as _Python modules.
+| 
+| Here's a `demo <https://www.youtube.com/watch?v=9Xt7X_Iqg6E>`_ using the guided installer.
+
+
+Some of the features of Archinstall are:
+
+* **No external dependencies or installation requirements.** Runs without any external requirements or installation processes.
+
+* **Single threaded and context friendly.** The library always executed calls in sequential order to ensure installation-steps don't overlap or executes in the wrong order. It also supports *(and uses)* context wrappers to ensure things such as `sync` are called so data and configurations aren't lost.
+
+* **Supports standalone executable** The library can be compiled into a single executable and run on any system with or without Python. This is ideal for live mediums that don't want to ship Python as a big dependency.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Installing
+
+   installing/python
+   installing/binary
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Usage & Examples
+
+   examples/python
+   examples/binary
+   examples/scripting
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Programming Guide
+
+   programming_guide/requirements
+   programming_guide/basic_concept
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Getting help
+
+   help/discord
+   help/issues
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API Reference
+
+   archinstall/Installer
\ No newline at end of file
diff --git a/docs/installing/binary.rst b/docs/installing/binary.rst
new file mode 100644
index 00000000..2868d7f1
--- /dev/null
+++ b/docs/installing/binary.rst
@@ -0,0 +1,63 @@
+.. _installing.binary
+
+Binary executable
+=================
+
+Archinstall can be compiled into a standalone executable.
+For Arch Linux based systems, there's a package for this called `archinstall <https://archlinux.life/>`_.
+
+Using pacman
+------------
+
+Currently, you need to create your own mirror or use https://archlinux.life as a mirror.
+We'll use the later for this example as it's less of a process to explain.
+
+..note:: To create your own mirror, the `archiso <https://wiki.archlinux.org/index.php/archiso#Custom_local_repository>`_ wiki has a good tutorial and explanation of how and what a custom mirror does.
+
+Setup pacman to use https://archlinux.life as a mirror by modifying `/etc/pacman.conf` to contain the following:
+
+.. code-block::
+
+    [archlife]
+    Server = https://archlinux.life/$repo/os/$arch
+    SigLevel = Optional TrustAll
+
+You can now update your mirror-list and install `archinstall`.
+
+.. code-block::
+
+    sudo pacman -Syy
+    sudo pacman -S archinstall
+
+Using PKGBUILD
+--------------
+
+The `source <https://github.com/Torxed/archinstall>`_ contains a binary `PKGBUILD <https://github.com/Torxed/archinstall/tree/master/PKGBUILD/archinstall>`_ which can be either copied straight off the website. Or cloned using `git clone https://github.com/Torxed/archinstall`.
+
+Once you've obtained the `PKGBUILD`, building it is pretty straight forward.
+
+.. code-block::
+
+    makepkg -s
+
+Which should produce a `archinstall-X.x.z-1.pkg.tar.zst` that can be installed using:
+
+.. code-block::
+
+    sudo pacman -U archinstall-X.x.z-1.pkg.tar.zst
+
+.. note::
+
+    For a complete guide on the build process, please consult the wiki on `PKGBUILD <https://wiki.archlinux.org/index.php/PKGBUILD>`_.
+
+Manual compilation
+------------------
+
+You can compile the source manually without using a custom mirror or the `PKGBUILD` that is shipped.
+Simply clone or download the source, and while standing in the cloned folder `./archinstall`, execute:
+
+.. code-block::
+
+    nuitka3  --standalone --show-progress archinstall
+
+This requires the `nuitka <https://www.archlinux.org/packages/community/any/nuitka/>`_ package as well as `python3` to be installed locally.
\ No newline at end of file
diff --git a/docs/installing/python.rst b/docs/installing/python.rst
new file mode 100644
index 00000000..6ca2adb6
--- /dev/null
+++ b/docs/installing/python.rst
@@ -0,0 +1,49 @@
+.. _installing.python:
+
+Python library
+==============
+
+Archinstall shipps on `PyPi <https://pypi.org/>`_ as `archinstall <pypi.org/project/archinstall/>`_.
+But the library can be installed manually as well.
+
+Using PyPi
+----------
+
+The basic concept of PyPi applies using `pip`.
+Either as a global library:
+
+.. code-block::
+
+    sudo pip install archinstall
+
+Or as a user module:
+
+.. code-block::
+
+    pip --user install archinstall
+
+Which will allow you to start using the library.
+
+.. _installing.python.manual
+
+Manual installation
+-------------------
+
+You can either download the github repo as a zip archive.
+Or you can clone it, we'll clone it here but both methods work the same.
+
+.. code-block::
+
+    git clone https://github.com/Torxed/archinstall
+
+Either you can move the folder into your project and simply do
+
+.. code-block:: python
+
+    import archinstall
+
+Or you can use `setuptools <https://pypi.org/project/setuptools/>`_ to install it into the module path.
+
+.. code-block::
+
+    sudo python setup.py install
\ No newline at end of file