Browse Source

docs: move from README to docs/

Nils Schneider 10 years ago
parent
commit
38bac6a6ad
6 changed files with 149 additions and 122 deletions
  1. 4 96
      README.md
  2. 63 0
      docs/dev/basics.rst
  3. 0 20
      docs/dev/contribute.rst
  4. 31 0
      docs/features/autoupdater.rst
  5. 1 1
      docs/index.rst
  6. 50 5
      docs/user/getting_started.rst

+ 4 - 96
README.md

@@ -1,100 +1,8 @@
-To build Gluon, after checking out the repository change to the source root directory
-to  perform the following commands:
+Documentation (incomplete at this time, contribute if you can!) may be found at
+http://gluon.readthedocs.org/
 
 
-    git clone git://github.com/freifunk-gluon/site-ffhl.git site # Get the Freifunk Lübeck site repository - or use your own!
-    make update                                                  # Get other repositories used by Gluon
-    make                                                         # Build Gluon
-
-When calling make, the OpenWRT build environment is prepared/updated. To rebuild
-the images only, just use:
-
-    make images
-
-The built images can be found in the directory `images`. Of these, the factory
-images are to be used when flashing from the original firmware a device came with,
-and sysupgrade is to upgrade from other versions of Gluon or any other OpenWRT-based
-system.
-
-For the build reserve 6GB of disk space. The build requires packages
-for `subversion`, ncurses headers (`libncurses-dev`) and zlib headers
-(`libz-dev`).`
-
-
-There are two levels of `make clean`:
-
-    make clean
-
-will ensure all packages are rebuilt; this is what you normally want to do after an update.
-
-    make dirclean
-
-will clean the entire tree, so the toolchain will be rebuilt as well, which is
-not necessary in most cases, and will take a while.
-
-So all in all, to update and rebuild a Gluon build tree, the following commands should be used:
-
-    git pull
-    (cd site && git pull)
-    make update
-    make clean
-    make
-
-
-# The autoupdater
-
-Gluon contains an automatic update system which can be configured in the site configuration.
-
-By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
-during development), but it can be enabled by setting the variable GLUON_BRANCH when building
-to override the default branch set in the set in the site configuration.
-
-A manifest file for the updater can be generated with `make manifest`. A signing script (using
-ecdsautils) can by found in the `contrib` directory.
-
-A fully automated nightly build could use the following commands:
-
-    git pull
-    (cd site && git pull)
-    make update
-    make clean
-    make -j5 GLUON_BRANCH=experimental
-    make manifest GLUON_BRANCH=experimental
-    contrib/sign.sh $SECRETKEY images/sysupgrade/experimental.manifest
-    cp -r images /where/to/put/this/experimental
-    mv /where/to/put/this/experimental/experimental.manifest /where/to/put/this/experimental/manifest
-
-
-# Development
+If you're new to Gluon and ready to get your feet wet, have a look at the
+[Getting Started Guide]([http://gluon.readthedocs.org/en/latest/user/getting_started.html).
 
 
 **Gluon IRC channel: `#gluon` in hackint**
 **Gluon IRC channel: `#gluon` in hackint**
 
 
-To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
-rerun
-
-	make update
-
-`make update` also applies the patches that can be found in the directories found in
-`patches`; the resulting branch will be called `patched`, while the commit specified in `modules`
-can be refered to by the branch `base`.
-
-	make unpatch
-
-sets the repositories to the `base` branch,
-
-	make patch
-
-re-applies the patches by resetting the `patched` branch to `base` and calling `git am`
-for the patch files. Calling `make` or a similar command after calling `make unpatch`
-is generally not a good idea.
-
-After new patches have been commited on top of the patched branch (or existing commits
-since the base commit have been edited or removed), the patch directories can be regenerated
-using
-
-	make update-patches
-
-If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch
-and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem.
-
-Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
-commits, making `git reflog` the only way to recover them!

+ 63 - 0
docs/dev/basics.rst

@@ -0,0 +1,63 @@
+Development Basics
+==================
+
+Gluon's source is kept in `git repositories`_ at GitHub.
+
+.. _git repositories: https://github.com/freifunk-gluon
+
+Bug Tracker
+-----------
+
+The `main repo`_ does have issues enabled. 
+
+.. _main repo: https://github.com/freifunk-gluon/gluon
+
+IRC
+---
+
+Gluon's developers frequent `#gluon on hackint`_. You're welcome to join us!
+
+.. _#gluon on hackint: irc://irc.hackint.org/#gluon
+
+
+Working with repositories
+-------------------------
+
+To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
+rerun
+
+::
+
+	make update
+
+`make update` also applies the patches that can be found in the directories found in
+`patches`; the resulting branch will be called `patched`, while the commit specified in `modules`
+can be refered to by the branch `base`.
+
+::
+
+	make unpatch
+
+sets the repositories to the `base` branch,
+
+::
+
+	make patch
+
+re-applies the patches by resetting the `patched` branch to `base` and calling `git am`
+for the patch files. Calling `make` or a similar command after calling `make unpatch`
+is generally not a good idea.
+
+After new patches have been commited on top of the patched branch (or existing commits
+since the base commit have been edited or removed), the patch directories can be regenerated
+using
+
+::
+
+	make update-patches
+
+If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch
+and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem.
+
+Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
+commits, making `git reflog` the only way to recover them!

+ 0 - 20
docs/dev/contribute.rst

@@ -1,20 +0,0 @@
-Contributing to Gluon
-=====================
-
-Gluon's source is kept in `git repositories`_ at GitHub.
-
-.. _git repositories: https://github.com/freifunk-gluon
-
-Bug Tracker
------------
-
-The `main repo`_ does have issues enabled. 
-
-.. _main repo: https://github.com/freifunk-gluon/gluon
-
-IRC
----
-
-Gluon's developers frequent `#gluon on hackint`_. You're welcome to join us!
-
-.. _#gluon on hackint: irc://irc.hackint.org/#gluon

+ 31 - 0
docs/features/autoupdater.rst

@@ -1,6 +1,33 @@
 Autoupdater
 Autoupdater
 ===========
 ===========
 
 
+Gluon contains an automatic update system which can be configured in the site configuration.
+
+Building Images
+---------------
+
+By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
+during development), but it can be enabled by setting the variable GLUON_BRANCH when building
+to override the default branch set in the set in the site configuration.
+
+A manifest file for the updater can be generated with `make manifest`. A signing script (using
+ecdsautils) can by found in the `contrib` directory.
+
+A fully automated nightly build could use the following commands:
+
+::
+
+    git pull
+    (cd site && git pull)
+    make update
+    make clean
+    make -j5 GLUON_BRANCH=experimental
+    make manifest GLUON_BRANCH=experimental
+    contrib/sign.sh $SECRETKEY images/sysupgrade/experimental.manifest
+    cp -r images /where/to/put/this/experimental
+    mv /where/to/put/this/experimental/experimental.manifest /where/to/put/this/experimental/manifest
+
+
 Infrastructure
 Infrastructure
 --------------
 --------------
 
 
@@ -28,6 +55,8 @@ The server should be available via IPv6.
 Command Line
 Command Line
 ------------
 ------------
 
 
+These commands can be used on a node.
+
 ::
 ::
 
 
    # Update with some probability
    # Update with some probability
@@ -37,3 +66,5 @@ Command Line
 
 
    # Force Update Check
    # Force Update Check
    autoupdater -f
    autoupdater -f
+
+

+ 1 - 1
docs/index.rst

@@ -48,7 +48,7 @@ Developer Documentation
 .. toctree::
 .. toctree::
    :maxdepth: 2
    :maxdepth: 2
 
 
-   dev/contribute
+   dev/basics
    dev/architecture
    dev/architecture
    dev/repositories
    dev/repositories
    dev/packages
    dev/packages

+ 50 - 5
docs/user/getting_started.rst

@@ -1,10 +1,55 @@
 Getting Started
 Getting Started
 ===============
 ===============
 
 
+To build Gluon, after checking out the repository change to the source root directory
+to  perform the following commands:
+
+::
+
+    git clone git://github.com/freifunk-gluon/site-ffhl.git site # Get the Freifunk Lübeck site repository - or use your own!
+    make update                                                  # Get other repositories used by Gluon
+    make                                                         # Build Gluon
+
+When calling make, the OpenWRT build environment is prepared/updated. To rebuild
+the images only, just use:
+
+::
+
+    make images
+
+The built images can be found in the directory `images`. Of these, the factory
+images are to be used when flashing from the original firmware a device came with,
+and sysupgrade is to upgrade from other versions of Gluon or any other OpenWRT-based
+system.
+
+For the build reserve 6GB of disk space. The build requires packages
+for `subversion`, ncurses headers (`libncurses-dev`) and zlib headers
+(`libz-dev`).
+
+
+There are two levels of `make clean`:
+
 ::
 ::
 
 
-  git clone https://github.com/freifunk-gluon/gluon.git
-  cd gluon
-  git clone git://github.com/freifunk-gluon/site-ffhl.git site
-  make update
-  make
+    make clean
+
+will ensure all packages are rebuilt; this is what you normally want to do after an update.
+
+::
+
+    make dirclean
+
+will clean the entire tree, so the toolchain will be rebuilt as well, which is
+not necessary in most cases, and will take a while.
+
+So all in all, to update and rebuild a Gluon build tree, the following commands should be used:
+
+::
+
+    git pull
+    (cd site && git pull)
+    make update
+    make clean
+    make
+
+