git push origin masterMerge branch 'ThomasWaldmann-docs'

.travis.yml

@@ -1,4 +1,4 @@
-# To mimic README.md installation and hacking instructions as much as
+# To mimic README.rst installation and hacking instructions as much as
 # possible, this config file instructs Travis CI to create a build
 # environment for each supported Python version, and then for each of
 # those it runs tox with two environments: lint and pyXX corresponding

CHANGES.rst

@@ -0,0 +1,27 @@
+ChangeLog
+=========
+
+Please note:
+the change log will only get updated after first release - for now please use the
+`commit log <https://github.com/letsencrypt/lets-encrypt-preview/commits/master>`_.
+
+
+Release 0.1.0 (not released yet)
+--------------------------------
+
+New Features:
+
+* ...
+
+Fixes:
+
+* ...
+
+Other changes:
+
+* ...
+
+Release 0.0.0 (not released yet)
+--------------------------------
+
+Initial release.

README.md

@@ -1,143 +0,0 @@
-# Let's Encrypt
-
-[![Build Status]
-(https://travis-ci.org/letsencrypt/lets-encrypt-preview.svg?branch=master)]
-(https://travis-ci.org/letsencrypt/lets-encrypt-preview)
-
-## Disclaimer
-
-This is the [Let's Encrypt] Agent **DEVELOPER PREVIEW** repository.
-
-**DO NOT RUN THIS CODE ON A PRODUCTION WEBSERVER. IT WILL INSTALL
-CERTIFICATES SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR
-USERS.**
-
-This code is intended for testing, demonstration, and integration
-engineering with OSes and hosting platforms. For the time being
-project focuses on Linux and Apache, though we will be expanding
-it to other platforms.
-
-## Running the demo code
-
-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)).
-Therefore, prerequisites for other platforms listed below are provided
-mainly for the [developers](#hacking) reference.
-
-### Prerequisites
-
-In general:
-
-* [swig] is required for compiling [m2crypto]
-* [augeas] is required for the `python-augeas` bindings
-
-#### Ubuntu
-
-```
-sudo apt-get install python python-setuptools python-virtualenv \
-  python-dev gcc swig dialog libaugeas0 libssl-dev ca-certificates
-```
-
-#### Mac OSX
-
-`sudo brew install augeas swig`
-
-### Installation
-
-```
-virtualenv --no-site-packages -p python2 venv
-./venv/bin/python setup.py install
-sudo ./venv/bin/letsencrypt
-```
-
-## Hacking
-
-In order to start hacking, you will first have to create a development
-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 following tools are there to help 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 lint` checks the style of the whole project,
-  while `./venv/bin/pylint --rcfile=.pylintrc file` will check a single `file` only.
-
-## Documentation
-
-The official documentation is available at
-https://letsencrypt.readthedocs.org.
-
-In order to generate the Sphinx documentation, run the following
-commands.
-
-```
-./venv/bin/python setup.py docs
-cd docs
-make clean html SPHINXBUILD=../venv/bin/sphinx-build
-```
-
-This should generate documentation in the `docs/_build/html`
-directory.
-
-### Coding style
-
-Most importantly, **be consistent with the rest of the code**, please.
-
-1. Read [PEP 8 - Style Guide for Python Code]
-(https://www.python.org/dev/peps/pep-0008).
-
-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:
-
-   ```python
-   def foo(arg):
-       """Short description.
-
-       :param int arg: Some number.
-
-       :returns: Argument
-       :rtype: int
-
-       """
-       return arg
-   ```
-
-3. Remember to use `./venv/bin/pylint`.
-
-## Command line usage
-
-The letsencrypt commandline tool has a builtin help:
-
-```
-letsencrypt --help
-```
-
-## More Information
-
-- Further setup, documentation and open projects are available in the
-  [Wiki].
-
-- Join us at our IRC channel: #letsencrypt at [Freenode].
-
-- Client software development can be discussed on this [mailing
-  list]. To subscribe without a Google account, send an email to
-  client-dev+subscribe@letsencrypt.org.
-
-
-[augeas]: http://augeas.net
-[Freenode]: https://freenode.net
-[Let's Encrypt]: https://letsencrypt.org
-[m2crypto]: https://github.com/M2Crypto/M2Crypto
-[mailing list]: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev
-[swig]: http://www.swig.org
-[wiki]: https://github.com/letsencrypt/lets-encrypt-preview/wiki

README.rst

@@ -0,0 +1,79 @@
+About the Let's Encrypt Client
+==============================
+
+In short: getting and installing SSL/TLS certificates made easy (`watch demo video`_).
+
+The Let's Encrypt Client is a tool to automatically receive and install
+X.509 certificates to enable TLS on servers. The client will
+interoperate with the Let's Encrypt CA which will be issuing browser-trusted
+certificates for free beginning the summer of 2015.
+
+It's all automated:
+
+* The tool will prove domain control to the CA and submit a CSR (Certificate
+  Signing Request).
+* If domain control has been proven, a certificate will get issued and the tool
+  will automatically install it.
+
+All you need to do is:
+
+::
+
+   user@www:~$ sudo letsencrypt www.example.org
+
+
+**Encrypt ALL the things!**
+
+
+.. 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
+----------
+
+This is a **DEVELOPER PREVIEW** intended for developers and testers only.
+
+**DO NOT RUN THIS CODE ON A PRODUCTION SERVER. IT WILL INSTALL CERTIFICATES
+SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR USERS.**
+
+
+Current Features
+----------------
+
+* web servers supported:
+
+  - apache2.x (tested and working on Ubuntu Linux)
+
+* the private key is generated locally on your system
+* can talk to the Let's Encrypt (demo) CA or optionally to other ACME
+  compliant services
+* can get domain-validated (DV) certificates
+* can revoke certificates
+* adjustable RSA key bitlength (2048 (default), 4096, ...)
+* optionally can install a http->https redirect, so your site effectively
+  runs https only
+* fully automated
+* configuration changes are logged and can be reverted using the CLI
+* text and ncurses UI
+* Free and Open Source Software, made with Python.
+
+
+Links
+-----
+
+Documentation: https://letsencrypt.readthedocs.org/
+
+Software project: https://github.com/letsencrypt/lets-encrypt-preview
+
+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)
+
+.. _Freenode: https://freenode.net
+.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev

docs/api.rst

@@ -0,0 +1,8 @@
+=================
+API Documentation
+=================
+
+.. toctree::
+   :glob:
+
+   api/**

docs/index.rst

@@ -1,18 +1,17 @@
-.. Let's Encrypt documentation master file, created by
+Welcome to the Let's Encrypt client documentation!
-   sphinx-quickstart on Sun Nov 23 20:35:21 2014.
+==================================================
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Let's Encrypt's documentation!
-=========================================
-
-API documentation
------------------
 
 .. toctree::
-   :glob:
+   :maxdepth: 2
 
-   api/**
+   intro
+   using
+   project
+
+.. toctree::
+   :maxdepth: 1
+
+   api
 
 
 Indices and tables
@@ -21,4 +20,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/intro.rst

@@ -0,0 +1,6 @@
+============
+Introduction
+============
+
+.. include:: ../README.rst
+.. include:: ../CHANGES.rst

docs/project.rst

@@ -0,0 +1,77 @@
+================================
+The Let's Encrypt Client Project
+================================
+
+.. _hacking:
+
+Hacking
+=======
+
+In order to start hacking, you will first have to create a development
+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 :ref:`coding-style`.
+
+The following tools are there to help 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 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
+============
+
+Please:
+
+1. **Be consistent with the rest of the code**.
+
+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.
+
+            :returns: Argument
+            :rtype: int
+
+            """
+            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
+==========================
+
+In order to generate the Sphinx documentation, run the following commands.
+
+::
+
+    ./venv/bin/python setup.py docs
+    cd docs
+    make clean html SPHINXBUILD=../venv/bin/sphinx-build
+
+
+This should generate documentation in the ``docs/_build/html`` directory.

docs/using.rst

@@ -0,0 +1,60 @@
+==============================
+Using the Let's Encrypt client
+==============================
+
+Prerequisites
+=============
+
+The demo code is supported and known to work on **Ubuntu only** (even
+closely related `Debian is known to fail`_).
+
+Therefore, prerequisites for other platforms listed below are provided
+mainly for the :ref:`developers <hacking>` reference.
+
+In general:
+
+* `swig`_ is required for compiling `m2crypto`_
+* `augeas`_ is required for the ``python-augeas`` bindings
+
+.. _Debian is known to fail: https://github.com/letsencrypt/lets-encrypt-preview/issues/68
+
+Ubuntu
+------
+
+::
+
+    sudo apt-get install python python-setuptools python-virtualenv python-dev \
+                 gcc swig dialog libaugeas0 libssl-dev ca-certificates
+
+
+Mac OSX
+-------
+
+::
+
+    sudo brew install augeas swig
+
+
+Installation
+============
+
+::
+
+    virtualenv --no-site-packages -p python2 venv
+    ./venv/bin/python setup.py install
+    sudo ./venv/bin/letsencrypt
+
+
+Usage
+=====
+
+The letsencrypt commandline tool has a builtin help:
+
+::
+
+   letsencrypt --help
+
+
+.. _augeas: http://augeas.net/
+.. _m2crypto: https://github.com/M2Crypto/M2Crypto
+.. _swig: http://www.swig.org/