From 0a14007db229000e0901ccd1c3cc188f5749f7e8 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 25 Jan 2015 21:30:24 +0100 Subject: [PATCH 1/2] refactor docs, please check - README has only the most important infos that a new reader needs in his first minute of contact with the project (to decide whether it is interesting or not) - CHANGES shall later be a curated change log (== important changes between releases) - separate docs into intro, using, project - intro docs = include README, CHANGES (avoid duplication) --- .travis.yml | 2 +- CHANGES.rst | 27 +++++++++ README.md | 143 ----------------------------------------------- README.rst | 78 ++++++++++++++++++++++++++ docs/index.rst | 19 ++----- docs/intro.rst | 6 ++ docs/project.rst | 78 ++++++++++++++++++++++++++ docs/using.rst | 58 +++++++++++++++++++ 8 files changed, 254 insertions(+), 157 deletions(-) create mode 100644 CHANGES.rst delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/intro.rst create mode 100644 docs/project.rst create mode 100644 docs/using.rst diff --git a/.travis.yml b/.travis.yml index 54ed84263..bed4f6d30 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..6ef5ee373 --- /dev/null +++ b/CHANGES.rst @@ -0,0 +1,27 @@ +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 + + +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..07f98dfca --- /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. + +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 + + +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.** + + +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 can be rolled back N checkpoints +* 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/index.rst b/docs/index.rst index c636507df..0387269ab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,18 +1,12 @@ -.. 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 Indices and tables @@ -21,4 +15,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..57010b8e2 --- /dev/null +++ b/docs/project.rst @@ -0,0 +1,78 @@ +================================ +The Let's Encrypt Client Project +================================ + +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. + + +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: + +:: + + def foo(arg): + """Short description. + + :param int arg: Some number. + + :returns: Argument + :rtype: int + + """ + return arg + +3. Remember to use `./venv/bin/pylint`. + + +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. + +API documentation +================= + +.. toctree:: + :glob: + + api/** diff --git a/docs/using.rst b/docs/using.rst new file mode 100644 index 000000000..cda2d7ec4 --- /dev/null +++ b/docs/using.rst @@ -0,0 +1,58 @@ +============================== +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] +(https://github.com/letsencrypt/lets-encrypt-preview/issues/68)). + +Therefore, prerequisites for other platforms listed below are provided +mainly for the [developers](#hacking) reference. + +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 + + +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/ From fb2d8061c829c88c1b4db3cbe0b5ab4078b791e6 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 26 Jan 2015 14:58:24 +0100 Subject: [PATCH 2/2] 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