diff --git a/.travis.yml b/.travis.yml index 4ef4bb735..b23cfe540 100644 --- a/.travis.yml +++ b/.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 diff --git a/CHANGES.rst b/CHANGES.rst new file mode 100644 index 000000000..741d9bc7c --- /dev/null +++ b/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 `_. + + +Release 0.1.0 (not released yet) +-------------------------------- + +New Features: + +* ... + +Fixes: + +* ... + +Other changes: + +* ... + +Release 0.0.0 (not released yet) +-------------------------------- + +Initial release. diff --git a/README.md b/README.md deleted file mode 100644 index 320943156..000000000 --- a/README.md +++ /dev/null @@ -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 diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..c66fcabf6 --- /dev/null +++ b/README.rst @@ -0,0 +1,78 @@ +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 that talks to the Let's Encrypt CA +so you can comfortably and quickly get trusted TLS certificates that just +work without warnings in every browser. + +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 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 c636507df..b290b2231 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,18 +1,17 @@ -.. Let's Encrypt documentation master file, created by - 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 ------------------ +Welcome to the Let's Encrypt client 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` - diff --git a/docs/intro.rst b/docs/intro.rst new file mode 100644 index 000000000..188ff4302 --- /dev/null +++ b/docs/intro.rst @@ -0,0 +1,6 @@ +============ +Introduction +============ + +.. include:: ../README.rst +.. include:: ../CHANGES.rst diff --git a/docs/project.rst b/docs/project.rst new file mode 100644 index 000000000..fa59c1af3 --- /dev/null +++ b/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. diff --git a/docs/using.rst b/docs/using.rst new file mode 100644 index 000000000..441bf1623 --- /dev/null +++ b/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 ` 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/