improve documentation

- README
- restrict sphinx documentation to the API
- update the Makefiles

Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>

Makefile

@@ -39,10 +39,7 @@ clean:
 	-find . -name auth -exec rm -vf {}/password {}/username \;
 	@$(MAKE) -C clean
 
-man:
-	@$(MAKE) -C man
-
-doc:
+docs:
 	@$(MAKE) -C docs
 
 targz: ../$(TARGZ)

README.md

@@ -63,14 +63,16 @@ Bugs, issues and contributions can be requested to both the mailing list or the
 
 ## Documentation
 
-The documentation is included (in .rst format) in the `docs` directory.
-Read it directly or generate nice html docs (python-sphinx needed) and/or
-the man page (python-docutils needed) while being in the `docs` dir via:
+All the current and updated documentation is at the [community's website][website].
 
-    'make doc' (user docs), 'make man' (man page only) or 'make' (both)
+### Dispose locally
 
-    (`make html` will simply create html versions of all *.rst files in /docs)
-
-The resulting user documentation will be in `docs/html`. The full user
-docs are also at: http://docs.offlineimap.org. Please see there for
-detailed information on how to install and configure OfflineImap.
+You might want to dispose the documentation locally. Get the sources of the website.
+For the other documentations, run the approppriate make target:
+```
+$ ./scripts/get-repository.sh website
+$ cd docs
+$ make html  # Require rst2html
+$ make man   # Require a2x
+$ make api   # Require sphinx
+```

docs/Makefile

@@ -9,7 +9,7 @@ RST2HTML=`type rst2html >/dev/null 2>&1 && echo rst2html || echo rst2html.py`
 RST2MAN=`type rst2man >/dev/null 2>&1 && echo rst2man || echo rst2man.py`
 SPHINXBUILD = sphinx-build
 
-all: man doc
+docs: man api
 
 html: $(HTML_TARGETS)
 
@@ -24,7 +24,7 @@ offlineimap.1: offlineimap.txt
 offlineimapui.7: offlineimapui.txt
 	a2x -v -f manpage $?
 
-doc:
+api:
 	$(SPHINXBUILD) -b html -d html/doctrees doc-src html
 
 websitedoc:

docs/doc-src/index.rst

@@ -5,9 +5,6 @@
 Welcome to OfflineIMAP's developer documentation
 ================================================
 
-**Developer documentation**
-  * :doc:`Advanced Git <GitAdvanced>`
-
 **Documented APIs**
 
 .. toctree::