Clean up documentation.

The leading "README." on each file seems excessive, especially
considering this is a "docs/" directory. This was removed to make
identifying specific files a bit easier. Appropriate file extensions
were also added.

Formatting was also cleaned up so nearly-rst documents could be
rendered properly.
Signed-off-by: NMichael Lustfield <michael@lustfield.net>

docs/README.first

-				Notes
-				=====
-
-o Please be careful: dak sends out lots of emails and if not
-  configured properly will happily send them to lots of people who
-  probably didn't want those emails.
-
-o Don't use the debian dak.conf, cron.* etc. as starting
-  points for your own configuration files, they're highly Debian
-  specific.  Start from scratch and refer to the security.debian.org
-  config files (-security) as they're a better example for a private
-  archive.
-
-		    What do all these scripts do?
-		    =============================
-
-Generic and generally useful
-----------------------------
-
-o To process queue/:
-
-  * dak process-upload - processes queue/unchecked
-  * dak process-new - allows ftp administrator to process queue/new and queue/byhand
-  * dak process-policy - processes policy queues (including new and byhand)
-
-o To generate indices files:
-
-  * dak dominate          - removes obsolete packages from suites
-  * dak generate-packages-sources2 - generate Packages, Sources
-  * dak generate-releases - generates Release
-
-o To clean things up:
-
-  * dak clean-suites - to remove obsolete files from the pool
-  * dak clean-queues - to remove obsolete/stray files from the queue
-  * dak rm - to remove package(s) from suite(s)
-  * dak override - to change individual override entries
-
-o Information display:
-
-  * dak ls - shows information about package(s)
-  * dak queue-report - shows information about package(s) in queue/
-  * dak override - can show you individual override entries
-  * dak graph - creates some pretty graphs of queue sizes over time
-
-Generic and useful, but only for those with existing archives
--------------------------------------------------------------
-
-o dak init-archive - initializes a projectb database from an existing archive
-
-Generic but not overly useful (in normal use)
----------------------------------------------
-
-o dak import-users-from-passwd - sync PostgreSQL users with system users
-o dak cruft-report - check for obsolete or duplicated packages
-o dak init-dirs - directory creation in the initial setup of an archive
-o dak check-archive - various sanity checks of the database and archive
-o dak control-overrides - manipulates/lists override entries
-o dak control-suite - removes/adds/lists package(s) from/to/for a suite
-o dak stats - produces various statistics
-o dak find-null-maintainers - checks for users with no packages in the archive
-
-Semi-generic
-------------
-
-To generate less-used indices files:
-
-o dak make-maintainers - generates Maintainers file used by, e.g. debbugs
-o dak make-overrides  - generates override.<foo> files
-
-Mostly Debian(.org) specific
-----------------------------
-
-o dak security-install - wrapper for Debian security team
-o dak import-ldap-fingerprints - syncs fingerprint and uid information with a debian.org LDAP DB
-
-Very Incomplete or otherwise not generally useful
--------------------------------------------------
-
-o dak init-db - currently only initializes a DB from a dak.conf config file
-o dak check-overrides - override cruft checker that doesn't work well with New Incoming
-
-Scripts invoked by other scripts
---------------------------------
-
-o dak examine-package - invoked by 'dak process-new' to "check" NEW packages
-
-			How do I get started?
-			=====================
-
-Please refer to setup/README for instructions how to setup dak.

docs/README.options

-Standard options
-----------------
-
--a/--architectures
--c/--component
--h/--help 
--n/--no-action
--s/--suite
--V/--version
-
-Exceptions:
-  dak process-unchecked - backwardly compatible options with dinstall
-  dak control-suite - ? hysterical raisins and testing compatibility

docs/README.assumptions → docs/assumptions.rst

 Assumptions
 -----------
 
-o Usernames do not contain ",". [dak import-users-from-passwd]
-o Package names and versions do not contain "_" [dak cruft-report]
-o Suites are case-independent in conf files, but forced lower case in use. [dak make-suite-file-list]
-o Components are case-sensitive. [dak make-suite-file-list]
-o There's always source of some sort
+- Usernames do not contain ",". [dak import-users-from-passwd]
+- Package names and versions do not contain "_" [dak cruft-report]
+- Suites are case-independent in conf files, but forced lower case in use. [dak make-suite-file-list]
+- Components are case-sensitive. [dak make-suite-file-list]
+- There's always source of some sort
 
-o If you have a large archive, you have a lot of memory and don't mind
+- If you have a large archive, you have a lot of memory and don't mind
   it being used. [dak make-suite-file-list[, dak import-archive]]
 
 [Very incomplete...]
-

docs/debian-specific.rst

 DEBIAN-SPECIFIC NOTES
-************************************************************************
+=====================
 
 Git, Salsa Project, Workflow
-------------------------------------------------------------------------
 
 General
-========================================================================
+-------
 Our git repositories are hosted by the Salsa_ Service and available in
 the FTP-Team_ group. The team has all FTPMasters_ set as owner, all
 other team members are developers. The team and most of our repositories
@@ -14,12 +13,14 @@ notes used within the team only.
 
 
 dak.git_
-========================================================================
+--------
+
 This project contains the main code running the Debian archive,
 processing uploads, managing the various suites and releases.
 
 Contributing and workflow
-........................................................................
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Development is done in the **master** branch, be it direct commits
 from FTPMasters_ or via merges from other people (anyone is welcome to
 contribute!).
@@ -57,7 +58,8 @@ From there, an action from one of the FTPMasters_ will move it into
 the archive.
 
 The famous ``deploy`` branch
-########################################################################
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 This branch is the code actually in use on the Debian machines, and it
 gets deployed (hence the name) on them automatically.
 
@@ -72,10 +74,10 @@ changes in master as well as preparing the merge commit into
 ``deploy`` is one single action.
 
 security archive
-------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~
 
 NEW processing
-========================================================================
+--------------
 
 ::
 
@@ -94,7 +96,8 @@ NEW processing
     cronon
 
 Built-Using
-========================================================================
+-----------
+
 Source packages referred to via Built-Using need to be included in the
 security archive:
 
@@ -106,7 +109,6 @@ If the .dsc is signed by an old key no longer in the keyring, use
 
 
 
-.. Links and Stuff
 .. _Salsa: http://salsa.debian.org/
 .. _FTP-Team: https://salsa.debian.org/ftp-team/
 .. _FTPMasters: https://www.debian.org/intro/organization#ftpmasters
@@ -115,4 +117,3 @@ If the .dsc is signed by an old key no longer in the keyring, use
 .. _gitlabsmrdocs: https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.html
 .. _gitlab MR documentation: https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.html
 .. |MR| replace:: Merge request
-

docs/development.rst

@@ -26,7 +26,7 @@ Generate some test packages::
 DAK Subshell
 ------------
 
-**NOTE:** Make sure the hostname configured correctly (/etc/hosts is sufficent).
+**NOTE:** Make sure the hostname is configured correctly (/etc/hosts is sufficient).
 
 Working with a development version of DAK is best done from a testing subshell.
 
@@ -48,7 +48,7 @@ The database can now be poked at using psql::
 
     psql -c 'select * from suite;'
 
-To populate the database such that it mimics the Debian archive::
+To populate the database, such that it mimics the Debian archive::
 
     setup_debian_like_archive
 
@@ -71,7 +71,7 @@ development and testing, the previously built packages can be used::
 This will create symlinks in the temporary upload location pointing at the
 packages that were previously generated.
 
-With packages uploaded (symlinked, copyied, etc.), they can now be processed::
+With packages uploaded (symlinked, copied, etc.), they can now be processed::
 
     process_uploads
 
@@ -88,7 +88,7 @@ Tests
 -----
 
 The full test suite can be run using ``integration-tests/run-tests``. This
-should not be done from wihin an existing subshell; one will be created.
+should not be done from within an existing subshell; one will be created.
 
 New tests should be written within subshells, as a "unit" separator and should
 include a comment.

docs/first.rst

+Notes
+=====
+
+- Please be careful: dak sends out a lot of emails and if not
+  configured properly will happily send them to lots of people who
+  probably didn't want those emails.
+
+- Don't use the debian dak.conf, cron.* etc. as starting
+  points for your own configuration files; they are highly Debian
+  specific. Start from scratch and refer to the security.debian.org
+  config files (-security) as they're a better example for a private
+  archive.
+
+What do all these scripts do?
+=============================
+
+Generic and generally useful
+----------------------------
+
+- To process queue/:
+
+  * ``dak process-upload`` - processes queue/unchecked
+  * ``dak process-new`` - allows ftp administrator to process queue/new and queue/byhand
+  * ``dak process-policy`` - processes policy queues (including new and byhand)
+
+- To generate indices files:
+
+  * ``dak dominate`` - removes obsolete packages from suites
+  * ``dak generate-packages-sources2`` - generate Packages, Sources
+  * ``dak generate-releases`` - generates Release
+
+- To clean things up:
+
+  * ``dak clean-suites`` - to remove obsolete files from the pool
+  * ``dak clean-queues`` - to remove obsolete/stray files from the queue
+  * ``dak rm`` - to remove package(s) from suite(s)
+  * ``dak override`` - to change individual override entries
+
+- Information display:
+
+  * ``dak ls`` - shows information about package(s)
+  * ``dak queue-report`` - shows information about package(s) in queue/
+  * ``dak override`` - can show you individual override entries
+  * ``dak graph`` - creates some pretty graphs of queue sizes over time
+
+Generic and useful, but only for those with existing archives
+-------------------------------------------------------------
+
+- ``dak init-archive`` - initializes a projectb database from an existing archive
+
+Generic but not overly useful (in normal use)
+---------------------------------------------
+
+- ``dak import-users-from-passwd`` - sync PostgreSQL users with system users
+- ``dak cruft-report`` - check for obsolete or duplicated packages
+- ``dak init-dirs`` - directory creation in the initial setup of an archive
+- ``dak check-archive`` - various sanity checks of the database and archive
+- ``dak control-overrides`` - manipulates/lists override entries
+- ``dak control-suite`` - removes/adds/lists package(s) from/to/for a suite
+- ``dak stats`` - produces various statistics
+- ``dak find-null-maintainers`` - checks for users with no packages in the archive
+
+Semi-generic
+------------
+
+To generate less-used indices files:
+
+- ``dak make-maintainers`` - generates Maintainers file used by, e.g. debbugs
+- ``dak make-overrides`` - generates override.<foo> files
+
+Mostly Debian(.org) specific
+----------------------------
+
+- ``dak security-install`` - wrapper for Debian security team
+- ``dak import-ldap-fingerprints`` - syncs fingerprint and uid information with a debian.org LDAP DB
+
+Very Incomplete or otherwise not generally useful
+-------------------------------------------------
+
+- ``dak init-db`` - currently only initializes a DB from a dak.conf config file
+- ``dak check-overrides`` - override cruft checker that doesn't work well with New Incoming
+
+Scripts invoked by other scripts
+--------------------------------
+
+- ``dak examine-package`` - invoked by 'dak process-new' to "check" NEW packages
+
+How do I get started?
+=====================
+
+Please refer to ``setup/development.rst`` for instructions on how to set up dak.

docs/options.rst

+Standard options
+================
+
+::
+    -a/--architectures
+    -c/--component
+    -h/--help 
+    -n/--no-action
+    -s/--suite
+    -V/--version
+
+Exceptions:
+
+- ``dak process-unchecked`` - backward-compatible options with dinstall
+- ``dak control-suite`` - ? hysterical raisins and testing compatibility