mirror of
https://github.com/certbot/certbot.git
synced 2026-07-28 08:05:31 +02:00
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)
This commit is contained in:
Thomas Waldmann
+1
-1
@@ -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
|
||||
|
||||
+27
@@ -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.
|
||||
@@ -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
|
||||
+78
@@ -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
|
||||
|
||||
|
||||
+6
-13
@@ -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`
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
============
|
||||
Introduction
|
||||
============
|
||||
|
||||
.. include:: ../README.rst
|
||||
.. include:: ../CHANGES.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/**
|
||||
@@ -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/
|
||||
Reference in New Issue
Block a user