From fb2d8061c829c88c1b4db3cbe0b5ab4078b791e6 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 26 Jan 2015 14:58:24 +0100 Subject: [PATCH] docs: markup fixes, separate section for api docs, link to demo video, improved phrasing --- CHANGES.rst | 6 ++--- README.rst | 14 +++++------ docs/api.rst | 8 +++++++ docs/index.rst | 5 ++++ docs/project.rst | 61 ++++++++++++++++++++++++------------------------ docs/using.rst | 10 ++++---- 6 files changed, 59 insertions(+), 45 deletions(-) create mode 100644 docs/api.rst diff --git a/CHANGES.rst b/CHANGES.rst index 6ef5ee373..741d9bc7c 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,9 +1,9 @@ ChangeLog ========= -Please note: the change log will only get updated after first release. - -Until then please use commit log: https://github.com/letsencrypt/lets-encrypt-preview/commits/master +Please note: +the change log will only get updated after first release - for now please use the +`commit log `_. Release 0.1.0 (not released yet) diff --git a/README.rst b/README.rst index 07f98dfca..c66fcabf6 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ About the Let's Encrypt Client ============================== -In short: getting and installing SSL/TLS certificates made easy. +In short: getting and installing SSL/TLS certificates made easy (`watch demo video`_). The Let's Encrypt Client is a tool that talks to the Let's Encrypt CA so you can comfortably and quickly get trusted TLS certificates that just @@ -27,6 +27,8 @@ All you need to do is: .. image:: https://travis-ci.org/letsencrypt/lets-encrypt-preview.svg?branch=master :target: https://travis-ci.org/letsencrypt/lets-encrypt-preview +.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU + Disclaimer ---------- @@ -37,8 +39,8 @@ This is a **DEVELOPER PREVIEW** intended for developers and testers only. SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR USERS.** -Features -======== +Current Features +---------------- * web servers supported: @@ -53,7 +55,7 @@ Features * optionally can install a http->https redirect, so your site effectively runs https only * fully automated -* configuration changes can be rolled back N checkpoints +* configuration changes are logged and can be reverted using the CLI * text and ncurses UI * Free and Open Source Software, made with Python. @@ -70,9 +72,7 @@ Main Website: https://letsencrypt.org/ IRC Channel: #letsencrypt on `Freenode`_ Mailing list: `client-dev`_ (to subscribe without a Google account, send an - email to client-dev+subscribe@letsencrypt.org) +email to client-dev+subscribe@letsencrypt.org) .. _Freenode: https://freenode.net .. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev - - diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 000000000..8668ec5d8 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,8 @@ +================= +API Documentation +================= + +.. toctree:: + :glob: + + api/** diff --git a/docs/index.rst b/docs/index.rst index 0387269ab..b290b2231 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,11 @@ Welcome to the Let's Encrypt client documentation! using project +.. toctree:: + :maxdepth: 1 + + api + Indices and tables ================== diff --git a/docs/project.rst b/docs/project.rst index 57010b8e2..fa59c1af3 100644 --- a/docs/project.rst +++ b/docs/project.rst @@ -2,6 +2,8 @@ The Let's Encrypt Client Project ================================ +.. _hacking: + Hacking ======= @@ -12,47 +14,52 @@ environment: ./venv/bin/python setup.py dev -The code base, including your pull requests, **must have 100% test statement -coverage and be compliant with the [coding style](#coding-style)**. +The code base, including your pull requests, **must** have 100% test statement +coverage **and** be compliant with the :ref:`coding-style`. The following tools are there to help you: -- `./venv/bin/tox` starts a full set of tests. Please make sure you +- ``./venv/bin/tox`` starts a full set of tests. Please make sure you run it before submitting a new pull request. -- `./venv/bin/tox -e cover` checks the test coverage only. +- ``./venv/bin/tox -e cover`` checks the test coverage only. -- `./venv/bin/tox -e lint` checks the style of the whole project, - while `./venv/bin/pylint --rcfile=.pylintrc file` will check a single `file` only. +- ``./venv/bin/tox -e lint`` checks the style of the whole project, + while ``./venv/bin/pylint --rcfile=.pylintrc file`` will check a single `file` only. +.. _coding-style: + Coding style ============ -Most importantly, **be consistent with the rest of the code**, please. +Please: -1. Read [PEP 8 - Style Guide for Python Code] -(https://www.python.org/dev/peps/pep-0008). +1. **Be consistent with the rest of the code**. -2. Follow [Google Python Style Guide] -(https://google-styleguide.googlecode.com/svn/trunk/pyguide.html), -with the exception that we use [Sphinx](http://sphinx-doc.org/)-style -documentation: +2. Read `PEP 8 - Style Guide for Python Code`_. -:: +3. Follow the `Google Python Style Guide`_, with the exception that we + use `Sphinx-style`_ documentation: - def foo(arg): - """Short description. + :: - :param int arg: Some number. + def foo(arg): + """Short description. - :returns: Argument - :rtype: int + :param int arg: Some number. - """ - return arg + :returns: Argument + :rtype: int -3. Remember to use `./venv/bin/pylint`. + """ + return arg + +4. Remember to use ``./venv/bin/pylint``. + +.. _Google Python Style Guide: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html +.. _Sphinx-style: http://sphinx-doc.org/ +.. _PEP 8 - Style Guide for Python Code: https://www.python.org/dev/peps/pep-0008 Updating the Documentation @@ -67,12 +74,4 @@ In order to generate the Sphinx documentation, run the following commands. make clean html SPHINXBUILD=../venv/bin/sphinx-build -This should generate documentation in the `docs/_build/html` directory. - -API documentation -================= - -.. toctree:: - :glob: - - api/** +This should generate documentation in the ``docs/_build/html`` directory. diff --git a/docs/using.rst b/docs/using.rst index cda2d7ec4..441bf1623 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -6,16 +6,17 @@ Prerequisites ============= The demo code is supported and known to work on **Ubuntu only** (even -closely related [Debian is known to fail] -(https://github.com/letsencrypt/lets-encrypt-preview/issues/68)). +closely related `Debian is known to fail`_). Therefore, prerequisites for other platforms listed below are provided -mainly for the [developers](#hacking) reference. +mainly for the :ref:`developers ` reference. In general: * `swig`_ is required for compiling `m2crypto`_ -* `augeas`_ is required for the `python-augeas` bindings +* `augeas`_ is required for the ``python-augeas`` bindings + +.. _Debian is known to fail: https://github.com/letsencrypt/lets-encrypt-preview/issues/68 Ubuntu ------ @@ -30,6 +31,7 @@ Mac OSX ------- :: + sudo brew install augeas swig