doc: update HACKING, CONTRIBUTING and INSTALL information

- use markdown more explicitly
 - update information on i18n and translation
 - move or delete redundant info from HACKING into CONTRIBUTING

Signed-off-by: Johannes Keyser <johanneskeyser@posteo.de>
Reviewed-by: Sunil Mohan Adapa <sunil@medhas.org>

CONTRIBUTING.md

@@ -1,3 +1,4 @@
+# Contributing
 Here are some contributing guidelines for authors and reviewers of code changes.
 The goal is a readable log of code changes, to enhance transparency of their
 purpose and simplify debugging. Consider these guidelines as best practices, not
@@ -19,8 +20,11 @@ Naming conventions:
 
 # For authors of patches
 * If you would like to contribute, but are unsure what to do, just ask. There
-  are usually also issues tagged as "beginners", which might be a good starting
+  are usually also issues tagged as 'beginner', which might be a good starting
-  point.
+  point to work on and have a known solution.  Also, other developers are ready
+  to guide you on the implementation for such tasks.
+  Feel free to pickup a task from the issue by announcing it on the issue or by
+  creating a new issue for whatever task you are going to work on.
 * To get your changes included, you must open a pull request (PR), to get them
   reviewed. Briefly, fork the repository to your account, and edit, commit and
   push there. Then you can create a PR to the main repository.

HACKING.md

@@ -11,65 +11,76 @@ The entire setup is automatic and requires about 4.5 GB of disk space.
 
 1. Install Vagrant and VirtualBox:
 
+   ```
    $ sudo apt-get install virtualbox vagrant
+   ```
 
 2. To download, setup, run, and configure a VM for Plinth development
    using Vagrant, simply execute in your Plinth development folder:
 
+   ```
    $ vagrant up
+   ```
 
 3. To access Plinth (from host), visit https://localhost:4430/plinth/
 
 4. Edit the source code in your host machine's Plinth development folder.
-   By default, this folder is shared within the VM, at /vagrant/.
+   By default, this folder is shared within the VM, at `/vagrant/`.
    To actually reflect the changes in the running VM, run on your host:
 
+   ```
    $ vagrant provision
+   ```
 
 ## Installing Dependencies
 
 Apart from dependencies listing in INSTALL.md file, Plinth may have additional
 dependencies required by modules of Plinth.  To install these, run:
 
-    $ sudo apt install -y $(plinth --list-dependencies)
+```
+$ sudo apt install -y $(plinth --list-dependencies)
+```
 
 ## Manually Setting Up for Development
 
-It is recommended that you use Vagrant to setup your development
+It is recommended that you use Vagrant to setup your development environment.
-environment.  However, for some reason, you wish setup manually, the
+However, for some reason, you wish setup manually, the following tips will help:
-following tips will help:
 
-1. Instead of running "setup.py install" after every source modification, run
+1. Instead of running `setup.py install` after every source modification, run
    the following command:
 
-    $ sudo python3 setup.py develop
+   ```
+   $ sudo python3 setup.py develop
+   ```
 
-    This will install the python package in a special development mode.  Run it
+   This will install the python package in a special development mode.  Run it
-    normally.  Any updates to the code (and core package data files) do not
+   normally.  Any updates to the code (and core package data files) do not
-    require re-installation after every modification.
+   require re-installation after every modification.
 
-    CherryPy web server also monitors changes to the source files and reloads
+   CherryPy web server also monitors changes to the source files and reloads
-    the server as soon as a file is modified.  Hence it is usually sufficient
+   the server as soon as a file is modified.  Hence it is usually sufficient
-    to modify the source and refresh the browser page to see the changes.
+   to modify the source and refresh the browser page to see the changes.
 
 2. Plinth also support running without installing (as much as possible).
    Simply run it as:
 
-    $ sudo ./run --debug
+   ```
+   $ sudo ./run --debug
+   ```
 
-    In this mode, Plinth runs in working directory without need for
+   In this mode, Plinth runs in working directory without need for
-    installation.  It uses the plinth.conf config file in the working
+   installation.  It uses the `plinth.conf` config file in the working
-    directory if no regular config file (/etc/plinth/plinth.conf) is found.
+   directory if no regular config file (`/etc/plinth/plinth.conf`) is found.
-    It creates all that data and runtime files in data/var/*.
+   It creates all that data and runtime files in `data/var/*`.
 
-    *Note:* This mode is supported only in a limited manner.  The following are
+   *Note:* This mode is supported only in a limited manner.  The following are
-    the unknown issues with it:
+   the unknown issues with it:
 
-    1. Help pages are also not built. Run 'make -C doc' manually.
+    1. Help pages are also not built. Run `make -C doc` manually.
 
-    2. Actions do not work when running as normal user without 'sudo' prefix.
+    2. Actions do not work when running as normal user without `sudo` prefix.
-       You need to add 'actions' directory to be allowed for 'sudo' commands.
+       You need to add `actions` directory to be allowed for `sudo` commands.
-       See data/etc/sudoers.d/plinth for a hint.
+       See `data/etc/sudoers.d/plinth` for a hint.
 
 ### Testing Inside a Virtual Machine
 
@@ -78,7 +89,7 @@ following tips will help:
 2. Share the source folder and mount it on virtual machine.  This could be done
    over NFS, SSH-fs or 'Shared Folders' feature on VirtualBox.
 
-3. Run 'setup.py develop' or 'setup.py install' as described above on guest
+3. Run `setup.py develop` or `setup.py install` as described above on guest
    machine.
 
 4. Access the guest machine's Plinth web UI from host after setting bridging or
@@ -86,37 +97,43 @@ following tips will help:
 
 ## Running Tests
 
-1. Run tests:
+To run tests:
 
-    $ python3 setup.py test
+```
+$ python3 setup.py test
+```
 
 ## Running the Test Coverage Analysis
 
-1. Run the coverage tool:
+To run the coverage tool:
 
-    $ python3 setup.py test_coverage
+```
+$ python3 setup.py test_coverage
+```
 
-    Invoking this command generates a binary-format '.coverage' data file in
+Invoking this command generates a binary-format `.coverage` data file in
-    the top-level project directory which is recreated with each run, and
+the top-level project directory which is recreated with each run, and
-    writes a set of HTML and other supporting files which comprise the
+writes a set of HTML and other supporting files which comprise the
-    browsable coverage report to the 'plinth/tests/coverage/report' directory.
+browsable coverage report to the `plinth/tests/coverage/report` directory.
-    Index.html presents the coverage summary, broken down by module.  Data
+`Index.html` presents the coverage summary, broken down by module.  Data
-    columns can be sorted by clicking on the column header or by using mnemonic
+columns can be sorted by clicking on the column header or by using mnemonic
-    hot-keys specified in the keyboard widget in the upper-right corner of the
+hot-keys specified in the keyboard widget in the upper-right corner of the
-    page.  Clicking on the name of a particular source file opens a page that
+page.  Clicking on the name of a particular source file opens a page that
-    displays the contents of that file, with color-coding in the left margin to
+displays the contents of that file, with color-coding in the left margin to
-    indicate which statements or branches were executed via the tests (green)
+indicate which statements or branches were executed via the tests (green)
-    and which statements or branches were not executed (red).
+and which statements or branches were not executed (red).
 
 ## Building the Documentation Separately
 
-Plinth man page is built from DocBook source in the doc/ directory.
+Plinth man page is built from DocBook source in the `doc/` directory.
 FreedomBox manual is downloaded from the wiki is also available there.
 Both these are build during the installation process.
 
-1. To build the documentation separately, run:
+To build the documentation separately, run:
 
-    $ make -C doc
+```
+$ make -C doc
+```
 
 ## Repository
 
@@ -127,52 +144,29 @@ Plinth is available from [GitHub](https://github.com/freedombox/plinth).
 You can report bugs on Plinth's [issue
 tracker](https://github.com/freedombox/Plinth/issues).
 
-For new developers looking to start contributing to the project, this
+See CONTRIBUTING.md for information how to best contribute code.
-is a good place to pick up a task to work on.  Tasks that are labeled
-as 'beginner' are easy to work on and have a known solution.  Also,
-other developers are ready to guide you on the implementation for such
-tasks.
-
-Feel free to pickup a task from the issue by announcing it on the
-issue or by creating a new issue for whatever task you are going to
-work on.
-
-## Submitting Your Changes
-
-Once you have completed implementing the solution, request a merge
-into the upstream.
-
-Pacthes can be submitted in either of the two ways:
-
-- Post your patches to the FreedomBox discuss mailing list.  Look at
-  Git documention on how to create submittable patches out of your
-  commits and post them to the list.
-
-- Create a pull request on Github.  For information on placing a merge
-  request, consult GitHub documentation.
-
-## Coding Practices
-
-Plinth confirms to [PEP 8](http://www.python.org/dev/peps/pep-0008/) Python
-coding standard. Before placing a merge request, you should check your code
-for errors with *flake8* and indent your code with *yapf*.
 
 ## Internationalization
 
-Every module should `from gettext import gettext as _` and wrap
+To mark text for translation, Plinth uses Django's translation strings.
-displayed strings with _().  We don't have the language stuff in place
+A module should e.g. `from django.utils.translation import ugettext as _`
-yet (we have no translation files), but we need to put the
+and wrap user-facing text with `_()`.  Use it like this:
-infrastructure in place for it from the start.  Use it like this:
 
-    log.error(_("Couldn't import %s: %s"), path, e)
+```python
+message = _('Application successfully installed and configured.')
+```
 
 ## Translations
 
-Introduce yourself on #freedombox IRC (irc.debian.org) and start translating
+The easiest way to start translating is with your browser, by using
-the PO file from your language directory from:
+[Weblate](https://hosted.weblate.org/projects/freedombox/plinth/).
-Plinth/plinth/locale/
+Your changes will automatically get pushed to the code repository.
-Introducing yourself is important since some work may have been done already
+
-on Debian translators discussion lists and Weblate localization platform.
+Alternatively, you can directly edit the `.po` file in your language directory
-https://hosted.weblate.org/projects/freedombox/plinth/
+`Plinth/plinth/locale/` and create a pull request (see CONTRIBUTING.md).
-https://www.debian.org/MailingLists/subscribe
+In that case, consider introducing yourself on #freedombox IRC (irc.debian.org),
+because some work may have been done already on the [Debian translators
+discussion lists](https://www.debian.org/MailingLists/subscribe)
+or the Weblate localization platform.
+
 For more information on translations: https://wiki.debian.org/FreedomBox/Translate

INSTALL.md

@@ -2,75 +2,89 @@
 
 1. Install the dependencies:
 
-    On a Debian based system, run:
+   On a Debian based system, run:
 
-    $ sudo apt-get install \
+   ```
-    augeas-tools \
+   $ sudo apt-get install \
-    dblatex \
+   augeas-tools \
-    docbook-utils \
+   dblatex \
-    gettext \
+   docbook-utils \
-    gir1.2-glib-2.0 \
+   gettext \
-    gir1.2-nm-1.0 \
+   gir1.2-glib-2.0 \
-    ldapscripts \
+   gir1.2-nm-1.0 \
-    libjs-bootstrap \
+   ldapscripts \
-    libjs-jquery \
+   libjs-bootstrap \
-    libjs-modernizr \
+   libjs-jquery \
-    make \
+   libjs-modernizr \
-    network-manager \
+   make \
-    ppp \
+   network-manager \
-    pppoe \
+   ppp \
-    python3 \
+   pppoe \
-    python3-apt \
+   python3 \
-    python3-augeas \
+   python3-apt \
-    python3-bootstrapform \
+   python3-augeas \
-    python3-cherrypy3 \
+   python3-bootstrapform \
-    python3-configobj \
+   python3-cherrypy3 \
-    python3-coverage \
+   python3-configobj \
-    python3-django \
+   python3-coverage \
-    python3-django-axes \
+   python3-django \
-    python3-django-captcha \
+   python3-django-axes \
-    python3-django-stronghold \
+   python3-django-captcha \
-    python3-gi \
+   python3-django-stronghold \
-    python3-psutil \
+   python3-gi \
-    python3-requests \
+   python3-psutil \
-    python3-ruamel.yaml \
+   python3-requests \
-    python3-setuptools \
+   python3-ruamel.yaml \
-    xmlto
+   python3-setuptools \
+   xmlto
+   ```
 
 2. Install Plinth:
 
-    Unzip the source into a directory.  Change to the directory containing the
+   Unzip the source into a directory.  Change to the directory containing the
-    program and run:
+   program and run:
 
-    $ sudo python3 setup.py install
+   ```
-    $ sudo apt install -y $(plinth --list-dependencies)
+   $ sudo python3 setup.py install
+   $ sudo apt install -y $(plinth --list-dependencies)
+   ```
 
 3. Run Plinth:
 
-    $ sudo plinth
+   ```
+   $ sudo plinth
+   ```
 
 4. Access Plinth UI:
 
-    Plinth UI should be accessible at http://localhost:8000/plinth
+   Plinth UI should be accessible at http://localhost:8000/plinth
 
 # Note on Django version:
 
 Django 1.11 is required to run Plinth. You can check the version by running:
 
-    $ django-admin --version
+```
+$ django-admin --version
+```
 
-If apt-get provided django<1.11, then follow the steps below:
+If apt-get provided django < 1.11, then follow the steps below:
 
 1. Uninstall older django versions:
 
-    $ sudo apt-get remove python3-django python3-django-stronghold \
+   ```
-    python3-bootstrap
+   $ sudo apt-get remove python3-django python3-django-stronghold \
+   python3-bootstrap
+   ```
 
 2. Install Python3 pip:
 
-    $ sudo apt-get install python3-pip
+   ```
+   $ sudo apt-get install python3-pip
+   ```
 
 3. Install django1.11 through pip:
 
-    $ sudo pip3 install django django-bootstrap-form django-stronghold \
+   ```
-    django-axes django-simple-captcha --upgrade
+   $ sudo pip3 install django django-bootstrap-form django-stronghold \
+   django-axes django-simple-captcha --upgrade
+   ```