doc: add sphinx/rst based documentation

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>

14 files changed, 164 insertions, 150 deletions

diff --git a/README b/README
index e9f9801..e89ec47 100644
--- a/README
+++ b/README
@@ -1,77 +1,16 @@
-DistroKit
----------
+README
+------
 
-This is the main repository for DistroKit, an Embedded Linux Board
-Support Package (BSP) for the PTXdist [1] Build System.
+The documentation is now available in the doc/ directory, with the
+starting point at
 
-The main task for PTXdist is to build a root filesystem and a flash
-image for the embedded system. PTXdist has a concept of separating the
-software configuration from the hardware platforms, so the first
-decision to be made is to select for which hardware DistroKit shall be
-built.
+	doc/intro.rst
 
+It can be built into HTML documentation with
 
-Installing PTXdist
-------------------
+	$ ptxdist docs-html
 
-DistroKit is built with ptxdist. In order to install ptxdist, download
-the tarball from [2]:
+Then point your browser to
 
-$ wget \
-  http://www.pengutronix.de/software/ptxdist/download/ptxdist-2016.01.0.tar.bz2
-
-Extract the tarball:
-
-$ tar xf ptxdist-2016.01.0 && cd ptxdist-2016.01.0
-
-Go to the extracted directory and run
-
-$ ./configure && make && sudo make install
-
-
-Selecting the Platform
-----------------------
-
-For the different hardware platforms, see the instructions about
-
-- how to install the toolchain
-- how to select the right platform
-- how to build the rootfs
-
-in README.<platform>.
-
-In order to build a BSP, you need a toolchain. The easiest way to get a
-toolchain is to install the debian packages for OSELAS.Toolchain:
-
-  http://www.pengutronix.de/oselas/toolchain/
-
-If you want to build the toolchain yourself, you can download the
-toolchain sources from
-
-  http://www.pengutronix.de/oselas/toolchain/download/
-
-and build them manually.
-
-
-Building DistroKit
-------------------
-
-Now everything is prepared to build the BSP:
-
-$ ptxdist images
-
-PTXdist determines the number of CPUs on your computer and runs the
-compiler with <twice the number of CPUs> instances in parallel.
-Nevertheless, building a root filesystem from the sources needs some
-time.
-
-
-References
-----------
-
-[1] PTXdist
-    http://www.pengutronix.de/software/ptxdist/
-
-[2] PTXdist Download Area
-    http://www.pengutronix.de/software/ptxdist/download/
+	Documentation/html/index.html
 
diff --git a/README.BeagleBone b/README.BeagleBone
deleted file mode 100644
index ecd2a61..0000000
--- a/README.BeagleBone
+++ /dev/null
@@ -1,20 +0,0 @@
-BeagleBone:
------------
-
-Install the toolchain:
-
-$ aptitude install \
-  oselas.toolchain-2014.12.1-arm-cortexa8-linux-gnueabihf-gcc-4.9.2-glibc-2.20-binutils-2.24-kernel-3.16-sanitized
-
-or visit [1] for manual installation.
-
-Select the platform:
-
-$ ptxdist platform \
-  configs/platform-beaglebone/platformconfig
-
-References
-----------
-
-[1] OSELAS Toolchain
-    http://www.pengutronix.de/oselas/toolchain/
diff --git a/README.Qemu b/README.Qemu
deleted file mode 100644
index 14bde33..0000000
--- a/README.Qemu
+++ /dev/null
@@ -1,20 +0,0 @@
-Qemu:
------
-
-Install the toolchain:
-
-$ aptitude install \
-  oselas.toolchain-2014.12.1-i686-atom-linux-gnu-gcc-4.9.2-glibc-2.20-binutils-2.24-kernel-3.16-sanitized
-
-or visit [1] for manual installation.
-
-Select the platform:
-
-$ ptxdist platform \
-  configs/platform-qemu/platformconfig
-
-References
-----------
-
-[1] OSELAS Toolchain
-    http://www.pengutronix.de/oselas/toolchain/
diff --git a/README.RaspberryPi b/README.RaspberryPi
deleted file mode 100644
index b4e04bf..0000000
--- a/README.RaspberryPi
+++ /dev/null
@@ -1,20 +0,0 @@
-Raspberry Pi:
--------------
-
-Install the toolchain:
-
-$ aptitude install \
-  oselas.toolchain-2014.12.1-arm-1136jfs-linux-gnueabihf-gcc-4.9.2-glibc-2.20-binutils-2.24-kernel-3.16-sanitized
-
-or visit [1] for manual installation.
-
-Select the platform:
-
-$ ptxdist platform \
-  configs/platform-rpi/platformconfig
-
-References
-----------
-
-[1] OSELAS Toolchain
-    http://www.pengutronix.de/oselas/toolchain/
diff --git a/README.RaspberryPi2 b/README.RaspberryPi2
deleted file mode 100644
index 6c04829..0000000
--- a/README.RaspberryPi2
+++ /dev/null
@@ -1,20 +0,0 @@
-Raspberry Pi2:
---------------
-
-Install the toolchain:
-
-$ aptitude install \
-  oselas.toolchain-2014.12.1-arm-v7a-linux-gnueabihf-gcc-4.9.2-glibc-2.20-binutils-2.24-kernel-3.16-sanitized
-
-or visit [1] for manual installation.
-
-Select the platform:
-
-$ ptxdist platform \
-  configs/platform-rpi2/platformconfig
-
-References
-----------
-
-[1] OSELAS Toolchain
-    http://www.pengutronix.de/oselas/toolchain/
diff --git a/doc/guru.rst b/doc/guru.rst
new file mode 100644
index 0000000..89667ad
--- /dev/null
+++ b/doc/guru.rst
@@ -0,0 +1,19 @@
+Welcome to the PTXdist Universe
+===============================
+
+.. toctree::
+   :glob:
+   :numbered: 2
+   :maxdepth: 3
+
+   welcome
+   environment
+   user_manual_section
+   dev_manual
+   ref_manual
+   daily_work_section
+   getting_help
+
+* :ref:`search`
+* :ref:`genindex`
+
diff --git a/doc/hardware.rst b/doc/hardware.rst
new file mode 100644
index 0000000..2691503
--- /dev/null
+++ b/doc/hardware.rst
@@ -0,0 +1,47 @@
+Hardware Platforms
+==================
+
+DistroKit supports a range of hardware, supported by the ptxdist
+platforms listed below. A platform can be built with one ``ptxdist
+images`` and shares the same cross compiler and binary format.
+
+
+v7a Platform
+------------
+
+The v7a platform is made for machines based on the ARMv7a architecture.
+Select the platform with
+
+::
+
+	$ ptxdist platform configs/platform-v7a/platformconfig
+	info: selected platformconfig:
+	      'configs/platform-v7a/platformconfig'
+
+To use the platform, the arm-v7a-linux-gnueabihf toolchain needs to be
+installed; if installed from the debian packages or tarballs, ptxdist
+is able to find and select the right toolchain with
+
+::
+
+	$ ptxdist toolchain
+	found and using toolchain:
+	'/opt/OSELAS.Toolchain-2016.06.1/arm-v7a-linux-gnueabihf/gcc-5.4.0-glibc-2.23-binutils-2.26-kernel-4.6-sanitized/bin'
+
+Now everything is prepared to build the platform with
+
+::
+
+	$ ptxdist images
+
+Hardware for the v7a Platform
+-----------------------------
+
+.. toctree::
+
+   hardware_v7a_qemu
+   hardware_v7a_beaglebone_white
+   hardware_v7a_beaglebone_black
+   hardware_v7a_raspi2
+   hardware_v7a_raspi3
+
diff --git a/doc/hardware_v7a_beaglebone_black.rst b/doc/hardware_v7a_beaglebone_black.rst
new file mode 100644
index 0000000..ce10d0b
--- /dev/null
+++ b/doc/hardware_v7a_beaglebone_black.rst
@@ -0,0 +1,5 @@
+Beaglebone Black
+================
+
+foo bar baz
+
diff --git a/doc/hardware_v7a_beaglebone_white.rst b/doc/hardware_v7a_beaglebone_white.rst
new file mode 100644
index 0000000..c62522e
--- /dev/null
+++ b/doc/hardware_v7a_beaglebone_white.rst
@@ -0,0 +1,5 @@
+Beaglebone White
+================
+
+foo bar baz
+
diff --git a/doc/hardware_v7a_qemu.rst b/doc/hardware_v7a_qemu.rst
new file mode 100644
index 0000000..7352f8c
--- /dev/null
+++ b/doc/hardware_v7a_qemu.rst
@@ -0,0 +1,6 @@
+QEmu
+====
+
+The v7a platform is ready to run in qemu, using the versatile express
+hardware simulation.
+
diff --git a/doc/hardware_v7a_raspi2.rst b/doc/hardware_v7a_raspi2.rst
new file mode 100644
index 0000000..f271772
--- /dev/null
+++ b/doc/hardware_v7a_raspi2.rst
@@ -0,0 +1,5 @@
+Raspberry Pi 2
+==============
+
+foo bar baz
+
diff --git a/doc/hardware_v7a_raspi3.rst b/doc/hardware_v7a_raspi3.rst
new file mode 100644
index 0000000..0be6c52
--- /dev/null
+++ b/doc/hardware_v7a_raspi3.rst
@@ -0,0 +1,5 @@
+Raspberry Pi 3
+==============
+
+foo bar baz
+
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..2ce9c75
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,15 @@
+Welcome to DistroKit
+====================
+
+.. toctree::
+   :glob:
+   :numbered:
+   :maxdepth: 2
+
+   intro
+   hardware
+   guru
+
+* :ref:`search`
+* :ref:`genindex`
+
diff --git a/doc/intro.rst b/doc/intro.rst
new file mode 100644
index 0000000..f02c4af
--- /dev/null
+++ b/doc/intro.rst
@@ -0,0 +1,48 @@
+Introduction
+============
+
+DistroKit is a Board Support Package (BSP) for the `PTXdist
+<http://www.ptxdist.org>`_ build system. It assembles a small (but not
+minimalistic) Embedded Linux system with modern components:
+
+- barebox bootloader
+- mainline kernel, as patch free as possible
+- systemd based init
+- NetworkManager for dbus based network configuration
+
+It can be used as a base for further BSP development.
+
+Installing the BSP
+------------------
+
+DistroKit is built with ptxdist. In order to install ptxdist,
+`download the tarball <http://www.pengutronix.de/software/ptxdist/download/ptxdist-|ptxdistVendorVersion|.tar.bz2>`_
+from the PTXdist Download Area.
+
+Extract the tarball:
+
+::
+
+        $ tar xf ptxdist-|ptxdistVendorVersion|.tar.bz2 && cd ptxdist-|ptxdistVendorVersion|
+
+Go to the extracted directory and run
+
+::
+
+        $ ./configure && make && sudo make install
+
+Installing the Toolchain
+------------------------
+
+In order to build a BSP, you need a toolchain. The easiest way to get a
+toolchain is to install the debian packages for OSELAS.Toolchain:
+
+        `<http://www.pengutronix.de/oselas/toolchain/>`_
+
+If you want to build the toolchain yourself, you can download the
+toolchain sources from
+
+        `<http://www.pengutronix.de/oselas/toolchain/download/>`_
+
+and build them manually.
+