From 5eeea9ed83fe4b778c95d5bcd96a8fe7a6b81c1c Mon Sep 17 00:00:00 2001 From: Nicolas Sebrecht Date: Fri, 13 Mar 2015 19:10:48 +0100 Subject: [PATCH] improve documentation - README - restrict sphinx documentation to the API - update the Makefiles Signed-off-by: Nicolas Sebrecht --- Makefile | 5 +---- README.md | 20 +++++++++++--------- docs/Makefile | 4 ++-- docs/doc-src/index.rst | 3 --- 4 files changed, 14 insertions(+), 18 deletions(-) diff --git a/Makefile b/Makefile index 4095171..3aca20a 100644 --- a/Makefile +++ b/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) diff --git a/README.md b/README.md index 1bbbd7f..cd97db2 100644 --- a/README.md +++ b/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 +``` diff --git a/docs/Makefile b/docs/Makefile index 1311bbf..6a7f8ea 100644 --- a/docs/Makefile +++ b/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: diff --git a/docs/doc-src/index.rst b/docs/doc-src/index.rst index 7335827..89f9ff0 100644 --- a/docs/doc-src/index.rst +++ b/docs/doc-src/index.rst @@ -5,9 +5,6 @@ Welcome to OfflineIMAP's developer documentation ================================================ -**Developer documentation** - * :doc:`Advanced Git ` - **Documented APIs** .. toctree::