nils/gluon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve user/getting_started, some minor fixes in user/site

Browse Source 
This commit basically does two things: it urges users always to use an own
git repository to manage the site configuration, and it removed all
mentions of "communities" from the "Getting started" page, as it was too
Freifunk-specific.

Other documentation pages (especially the site configuration docs) should
probably be adjusted as well.
This commit is contained in:
Matthias Schiffer 2015-11-05 22:42:34 +01:00
parent abd43c163c
commit 171b484735
2 changed files with 30 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/user/getting_started.rst
View File

@ -4,18 +4,20 @@ Getting Started
Selecting the right version
---------------------------
Gluon's releases are managed using `Git tags`_. If you're a community getting
Gluon's releases are managed using `Git tags`_. If you are just getting
started with Gluon we recommend to use the latest stable release of Gluon.
Take a look at the `list of gluon releases`_ and notice the latest release,
e.g. *v2014.3*.
e.g. *v2014.3*. Always get Gluon using git and don't try to download it
as a Zip archive as the archive will be missing version information.
Please keep in mind that a matching site configuration for your community
is required. Due to new features being added (or sometimes being removed)
the format of the site configuration changes slightly between releases.
Please keep in mind that there is no "default Gluon" build; a site configuration
is required to adjust Gluon to your needs. Due to new features being added (or
sometimes being removed) the format of the site configuration changes slightly
between releases. Please refer to our release notes for instructions to update
an old site configuration to a newer release of Gluon.
Recent releases (starting with *v2014.3.1*) will come with an example
configuration located in *docs/site-example/*.
An example configuration can be found in the Gluon repository at *docs/site-example/*.
.. _Git tags: http://git-scm.com/book/en/Git-Basics-Tagging
.. _list of gluon releases: https://github.com/freifunk-gluon/gluon/releases
@ -49,32 +51,34 @@ version you'd like to checkout, e.g. *v2015.1*.
This command will create a directory named *gluon/*.
It might also tell a scary message about being in a *detached state*.
**Don't panic!** Everything's fine.
Now, enter the freshly created directory:
::
Now, enter the freshly created directory::
cd gluon
It's time to add (or create) your site configuration.
So let's create the directory *site/*:
It's time to add (or create) your site configuration. If you already
have a site repository, just clone it::
::
git clone https://github.com/freifunk-duckburg/site-ffdb.git site
If you want to build a new site, create a new git repository *site/*::
mkdir site
cd site
git init
Copy *site.conf*, *site.mk* and *i18n* from *docs/site-example*:
::
Copy *site.conf*, *site.mk* and *i18n* from *docs/site-example*::
cp ../docs/site-example/site.conf .
cp ../docs/site-example/site.mk .
cp -r ../docs/site-example/i18n .
Edit these files to match your community, then go back to the top-level Gluon
directory and build Gluon:
Edit these files as you see fit and commit them into the site repository.
Extensive documentation about the site configuration can be found at:
:doc:`site`. The
site directory should always be a git repository by itself; committing site-specific files
to the Gluon main repository should be avoided, as it will make updates more complicated.
::
Next go back to the top-level Gluon directory and build Gluon::
cd ..
make update # Get other repositories used by Gluon
@ -83,7 +87,7 @@ directory and build Gluon:
When calling make, the OpenWrt build environment is prepared/updated.
In case of errors read the messages carefully and try to fix the stated issues (e.g. install tools not available yet).
``ar71xx-generic`` is the most common target and will generated images for most of the supported hardware.
``ar71xx-generic`` is the most common target and will generate images for most of the supported hardware.
To see a complete list of supported targets, call ``make`` without setting ``GLUON_TARGET``.
The built images can be found in the directory `output/images`. Of these, the factory
@ -93,9 +97,7 @@ system.
You should reserve about 10GB of disk space for each `GLUON_TARGET`.
There are two levels of `make clean`:
::
There are two levels of `make clean`::
make clean GLUON_TARGET=ar71xx-generic

10
docs/user/site.rst
View File

@ -1,5 +1,5 @@
Site
====
Site configuration
==================
The ``site`` consists of the files ``site.conf`` and ``site.mk``.
In the first community based values are defined, which both are processed
@ -279,8 +279,8 @@ The ``site.mk`` is a Makefile which should define constants
involved in the build process of Gluon.
GLUON_SITE_PACKAGES
Defines a list of packages which should installed additional
to the ``gluon_core`` package.
Defines a list of packages which should installed in addition
to the ``gluon-core`` package.
GLUON_RELEASE
The current release version Gluon should use.
@ -308,7 +308,7 @@ gluon-config-mode:pubkey
Information about the public VPN key on the reboot page.
gluon-config-mode:reboot
General information about the reboot page.
General information shown on the reboot page.
There is a POT file in the site example directory which can be used to create templates
for the language files. The command ``msginit -l en -i ../../docs/site-example/i18n/gluon-site.pot``