Improve documentation generation

Added a Makefile to generate the readme.rst and usage.rst files from the
application output.

Makefile

@@ -54,10 +54,7 @@ clean-test: ## remove test and coverage artifacts
 
 clean-docs: ## remove generated docs files
 	rm -rf dist/docs
-	rm -rf HELP
-	rm -rf HELP_UPDATE
-	rm -rf HELP_NEW
-	rm -rf HELP_CHECK
+	$(MAKE) -C docs clean
 
 lint: ## check style with flake8
 	flake8 src/smap tests
@@ -76,18 +73,8 @@ coverage: ## check code coverage quickly with the default Python
 	$(BROWSER) htmlcov/index.html
 
 usage: ## generate usage content by calling the program
-	echo 'Running  ``$ smap -h`` will give::' > HELP
-	echo >> HELP
-	smap -h | sed -e 's/^/  /' >> HELP
-	echo 'Running ``$ smap update -h`` will give::' > HELP_UPDATE
-	echo >> HELP_UPDATE
-	smap update -h | sed -e 's/^/  /' >> HELP_UPDATE
-	echo 'Running ``$ smap new -h`` will give::' > HELP_NEW
-	echo >> HELP_NEW
-	smap new -h | sed -e 's/^/  /' >> HELP_NEW
-	echo 'Running ``$ smap check -h`` will give::' > HELP_CHECK
-	echo >> HELP_CHECK
-	smap check -h | sed -e 's/^/  /' >> HELP_CHECK
+	$(MAKE) -C docs all
+	cp docs/readme.rst README.rst
 
 docs: usage ## generate Sphinx HTML documentation, including API docs
 	sphinx-build -E -b doctest docs dist/docs

README.rst

@@ -113,6 +113,164 @@ At the command line::
 
   pip install symver-smap
 
+Usage:
+------
+
+This project delivers a script, ``smap``. This is my first project in python, so feel free to point out ways to improve it.
+
+The sub-commands ``update`` and ``new`` expect a list of symbols given in stdin. The list of symbols are words separated by non-alphanumeric characters (matches with the regular expression ``[a-zA-Z0-9_]+``). For example::
+
+  symbol, another, one_more
+
+and::
+
+  symbol
+  another
+  one_more
+
+are valid inputs.
+
+The last sub-command, ``check``, expects only the path to the map file to be
+checked.
+
+tl;dr
+-----
+::
+
+  $ smap update lib_example.map < symbols_list
+
+or (setting an output)::
+
+  $ smap update lib_example.map -o new.map < symbols_list
+
+or::
+
+  $ cat symbols_list | smap update lib_example.map -o new.map
+
+or (to create a new map)::
+
+  $ cat symbols_list | smap new -r lib_example_1_0_0 -o new.map
+
+or (to check the content of a existing map)::
+
+  $ smap check my.map
+
+Long version
+------------
+
+Running  ``smap -h`` will give::
+
+  usage: smap [-h] {update,new,check} ...
+  
+  Helper tools for linker version script maintenance
+  
+  optional arguments:
+    -h, --help          show this help message and exit
+  
+  Subcommands:
+    {update,new,check}  These subcommands have their own set of options
+      update            Update the map file
+      new               Create a new map file
+      check             Check the map file
+  
+  Call a subcommand passing '-h' to see its specific options
+
+Call a subcommand passing '-h' to see its specific options
+There are three subcommands, ``update``, ``new``, and ``check``
+
+Running ``smap update -h`` will give::
+
+  usage: smap update [-h] [-o OUT] [-i INPUT] [-d]
+                     [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
+                     [-l LOGFILE] [-n NAME] [-v VERSION] [-r RELEASE]
+                     [--no_guess] [--allow-abi-break] [-a | --remove]
+                     file
+  
+  positional arguments:
+    file                  The map file being updated
+  
+  optional arguments:
+    -h, --help            show this help message and exit
+    -o OUT, --out OUT     Output file (defaults to stdout)
+    -i INPUT, --in INPUT  Read from this file instead of stdio
+    -d, --dry             Do everything, but do not modify the files
+    --verbosity {quiet,error,warning,info,debug}
+                          Set the program verbosity
+    --quiet               Makes the program quiet
+    --debug               Makes the program print debug info
+    -l LOGFILE, --logfile LOGFILE
+                          Log to this file
+    -n NAME, --name NAME  The name of the library (e.g. libx)
+    -v VERSION, --version VERSION
+                          The release version (e.g. 1_0_0 or 1.0.0)
+    -r RELEASE, --release RELEASE
+                          The full name of the release to be used (e.g.
+                          LIBX_1_0_0)
+    --no_guess            Disable next release name guessing
+    --allow-abi-break     Allow removing symbols, and to break ABI
+    -a, --add             Adds the symbols to the map file.
+    --remove              Remove the symbols from the map file. This breaks the
+                          ABI.
+  
+  A list of symbols is expected as the input. If a file is provided with '-i',
+  the symbols are read from the given file. Otherwise the symbols are read from
+  stdin.
+
+Running ``smap new -h`` will give::
+
+  usage: smap new [-h] [-o OUT] [-i INPUT] [-d]
+                  [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
+                  [-l LOGFILE] [-n NAME] [-v VERSION] [-r RELEASE] [--no_guess]
+  
+  optional arguments:
+    -h, --help            show this help message and exit
+    -o OUT, --out OUT     Output file (defaults to stdout)
+    -i INPUT, --in INPUT  Read from this file instead of stdio
+    -d, --dry             Do everything, but do not modify the files
+    --verbosity {quiet,error,warning,info,debug}
+                          Set the program verbosity
+    --quiet               Makes the program quiet
+    --debug               Makes the program print debug info
+    -l LOGFILE, --logfile LOGFILE
+                          Log to this file
+    -n NAME, --name NAME  The name of the library (e.g. libx)
+    -v VERSION, --version VERSION
+                          The release version (e.g. 1_0_0 or 1.0.0)
+    -r RELEASE, --release RELEASE
+                          The full name of the release to be used (e.g.
+                          LIBX_1_0_0)
+    --no_guess            Disable next release name guessing
+  
+  A list of symbols is expected as the input. If a file is provided with '-i',
+  the symbols are read from the given file. Otherwise the symbols are read from
+  stdin.
+
+Running ``smap check -h`` will give::
+
+  usage: smap check [-h]
+                    [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
+                    [-l LOGFILE]
+                    file
+  
+  positional arguments:
+    file                  The map file to be checked
+  
+  optional arguments:
+    -h, --help            show this help message and exit
+    --verbosity {quiet,error,warning,info,debug}
+                          Set the program verbosity
+    --quiet               Makes the program quiet
+    --debug               Makes the program print debug info
+    -l LOGFILE, --logfile LOGFILE
+                          Log to this file
+
+Import as a library:
+--------------------
+
+To use smap in a project as a library::
+
+	from smap import symver
+
 Documentation:
 --------------
 

docs/Makefile

@@ -0,0 +1,42 @@
+
+all: usage readme
+
+HELP:
+	echo 'Running  ``$ smap -h`` will give::' > HELP
+	echo >> HELP
+	smap -h | sed -e 's/^/  /' >> HELP
+
+HELP_NEW:
+	echo 'Running ``$ smap new -h`` will give::' > HELP_NEW
+	echo >> HELP_NEW
+	smap new -h | sed -e 's/^/  /' >> HELP_NEW
+
+HELP_UPDATE:
+	echo 'Running ``$ smap update -h`` will give::' > HELP_UPDATE
+	echo >> HELP_UPDATE
+	smap update -h | sed -e 's/^/  /' >> HELP_UPDATE
+
+HELP_CHECK:
+	echo 'Running ``$ smap check -h`` will give::' > HELP_CHECK
+	echo >> HELP_CHECK
+	smap check -h | sed -e 's/^/  /' >> HELP_CHECK
+
+usage: HELP HELP_NEW HELP_UPDATE HELP_CHECK
+	cp templates/usage.template usage.rst
+	sed -e '/HELP_PLACEHOLDER/ {' -e 'r HELP' -e 'd' -e '}' -i usage.rst
+	sed -e '/HELP_UPDATE_PLACEHOLDER/ {' -e 'r HELP_UPDATE' -e 'd' -e '}' -i usage.rst
+	sed -e '/HELP_NEW_PLACEHOLDER/ {' -e 'r HELP_NEW' -e 'd' -e '}' -i usage.rst
+	sed -e '/HELP_CHECK_PLACEHOLDER/ {' -e 'r HELP_CHECK' -e 'd' -e '}' -i usage.rst
+
+readme: HELP HELP_NEW HELP_UPDATE HELP_CHECK
+	cp templates/readme.template readme.rst
+	sed -e '/HELP_PLACEHOLDER/ {' -e 'r HELP' -e 'd' -e '}' -i readme.rst
+	sed -e '/HELP_UPDATE_PLACEHOLDER/ {' -e 'r HELP_UPDATE' -e 'd' -e '}' -i readme.rst
+	sed -e '/HELP_NEW_PLACEHOLDER/ {' -e 'r HELP_NEW' -e 'd' -e '}' -i readme.rst
+	sed -e '/HELP_CHECK_PLACEHOLDER/ {' -e 'r HELP_CHECK' -e 'd' -e '}' -i readme.rst
+
+.PHONY: clean
+
+clean:
+	rm -rf HELP HELP_NEW HELP_UPDATE HELP_CHECK
+