diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..bf19b18e1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,18 @@ + + +https://letsencrypt.readthedocs.org/en/latest/contributing.html diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index eda8045f3..000000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _hacking: - -Hacking -======= - -In order to start hacking, you will first have to create a development -environment. Start by `installing dependencies and setting up Let's Encrypt`_. - -Now you can install the development packages: - -:: - - ./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_. - -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. - -.. _installing dependencies and setting up Let's Encrypt: https://letsencrypt.readthedocs.org/en/latest/using.html - - -Vagrant -======= - -If you are a Vagrant user, Let's Encrypt comes with a Vagrantfile that automates -setting up a development environment in an Ubuntu 14.04 LTS VM. To set it up, -simply run ``vagrant up``. The repository is synced to ``/vagrant``, so you can -get started with: - -:: - - vagrant ssh - cd /vagrant - ./venv/bin/python setup.py install - sudo ./venv/bin/letsencrypt - -Support for other Linux distributions coming soon. - -**Note:** Unfortunately, Python distutils and, by extension, setup.py and tox, -use hard linking quite extensively. Hard linking is not supported by the -default sync filesystem in Vagrant. As a result, all actions with these -commands are *significantly slower* in Vagrant. One potential fix is to `use -NFS`_ (`related issue`_). - -.. _use NFS: http://docs.vagrantup.com/v2/synced-folders/nfs.html -.. _related issue: https://github.com/ClusterHQ/flocker/issues/516 - - -CODE COMPONENTS AND LAYOUT -========================== - -letsencrypt/acme - contains all protocol specific code -letsencrypt/client - all client code -letsencrypt/scripts - just the starting point of the code, main.py - -Plugin-architecture -------------------- - -Let's Encrypt has a plugin architecture to facilitate support for different -webservers, other TLS servers, and operating systems. - -The most common kind of plugin is a "Configurator", which is likely to -implement the "Authenticator" and "Installer" interfaces (though some -Configurators may implement just one of those). - -Defined here: -https://github.com/letsencrypt/lets-encrypt-preview/blob/master/letsencrypt/client/interfaces.py - -There are also "Display" plugins, which implement bindings to alternative UI -libraries. - -Authenticators --------------- - -Authenticators are plugins designed to solve challenges received from the -ACME server. From the protocol, there are essentially two different types -of challenges. Challenges that must be solved by individual plugins in -order to satisfy domain validation (dvsni, simpleHttps, dns) and client -specific challenges (recoveryToken, recoveryContact, pop). Client specific -challenges are always handled by the "Authenticator" -client_authenticator.py. Right now we have two DV Authenticators, -apache/configurator.py and the standalone_authenticator.py. The Standalone -and Apache authenticators only solve the DVSNI challenge currently. (You -can set which challenges your authenticator can handle through the -get_chall_pref(domain) function) - -(FYI: We also have a partial implementation for a dns_authenticator in a -separate branch). - -Challenge types are defined here... -( -https://github.com/letsencrypt/lets-encrypt-preview/blob/master/letsencrypt/client/constants.py#L16 -) - -Installer ---------- - -Installers classes exist to actually setup the certificate and be able -to enhance the configuration. (Turn on HSTS, redirect to HTTPS, etc). You -can indicate your abilities through the supported_enhancements call. We -currently only have one Installer written (still developing), -apache/configurator.py - -Installers and Authenticators will oftentimes be the same class/object. -Installers and Authenticators are kept separate because it should be -possible to use the standalone_authenticator (it sets up its own Python -server to perform challenges) with a program that cannot solve challenges -itself. (I am imagining MTA installers). - -*Display* - we currently offer a pythondialog and "text" mode for -displays. I have rewritten the interface which should be merged within the -next day (the rewrite is in the revoker branch of the repo and should be -merged within the next day) - -Here is what the display interface will look like -https://github.com/letsencrypt/lets-encrypt-preview/blob/revoker/letsencrypt/client/interfaces.py#L217 - -Augeus ------- - -Some plugins, especially those designed to reconfigure UNIX servers, can take -inherit from the augeus_configurator.py class in order to more efficiently -handle common operations on UNIX server configuration files. - - -.. _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. - -:: - - cd docs - make clean html SPHINXBUILD=../venv/bin/sphinx-build - - -This should generate documentation in the ``docs/_build/html`` directory. diff --git a/docs/conf.py b/docs/conf.py index 6e2c484ca..a6e5da4ff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,7 +101,7 @@ exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +default_role = 'py:obj' # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..e3b81b3d4 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,197 @@ +============ +Contributing +============ + +.. _hacking: + +Hacking +======= + +In order to start hacking, you will first have to create a development +environment. Start by :doc:`installing dependencies and setting up +Let's Encrypt `. + +Now you can install the development packages: + +.. code-block:: shell + + ./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. + +.. _installing dependencies and setting up Let's Encrypt: + https://letsencrypt.readthedocs.org/en/latest/using.html + + +Vagrant +------- + +If you are a Vagrant user, Let's Encrypt comes with a Vagrantfile that +automates setting up a development environment in an Ubuntu 14.04 +LTS VM. To set it up, simply run ``vagrant up``. The repository is +synced to ``/vagrant``, so you can get started with: + +.. code-block:: shell + + vagrant ssh + cd /vagrant + ./venv/bin/python setup.py install + sudo ./venv/bin/letsencrypt + +Support for other Linux distributions coming soon. + +.. note:: + Unfortunately, Python distutils and, by extension, setup.py and + tox, use hard linking quite extensively. Hard linking is not + supported by the default sync filesystem in Vagrant. As a result, + all actions with these commands are *significantly slower* in + Vagrant. One potential fix is to `use NFS`_ (`related issue`_). + +.. _use NFS: http://docs.vagrantup.com/v2/synced-folders/nfs.html +.. _related issue: https://github.com/ClusterHQ/flocker/issues/516 + + +Code components and layout +========================== + +letsencrypt/acme + contains all protocol specific code +letsencrypt/client + all client code +letsencrypt/scripts + just the starting point of the code, main.py + + +Plugin-architecture +------------------- + +Let's Encrypt has a plugin architecture to facilitate support for +different webservers, other TLS servers, and operating systems. + +The most common kind of plugin is a "Configurator", which is likely to +implement the `~letsencrypt.client.interfaces.IAuthenticator` and +`~letsencrypt.client.interfaces.IInstaller` interfaces (though some +Configurators may implement just one of those). + +There are also `~letsencrypt.client.interfaces.IDisplay` plugins, +which implement bindings to alternative UI libraries. + + +Authenticators +-------------- + +Authenticators are plugins designed to solve challenges received from +the ACME server. From the protocol, there are essentially two +different types of challenges. Challenges that must be solved by +individual plugins in order to satisfy domain validation (subclasses +of `~.DVChallenge`, i.e. `~.challenges.DVSNI`, +`~.challenges.SimpleHTTPS`, `~.challenges.DNS`) and client specific +challenges (subclasses of `~.ClientChallenge`, +i.e. `~.challenges.RecoveryToken`, `~.challenges.RecoveryContact`, +`~.challenges.ProofOfPossession`). Client specific challenges are +always handled by the `~.ClientAuthenticator`. Right now we have two +DV Authenticators, `~.ApacheConfigurator` and the +`~.StandaloneAuthenticator`. The Standalone and Apache authenticators +only solve the `~.challenges.DVSNI` challenge currently. (You can set +which challenges your authenticator can handle through the +:meth:`~.IAuthenticator.get_chall_pref`. + +(FYI: We also have a partial implementation for a `~.DNSAuthenticator` +in a separate branch). + + +Installer +--------- + +Installers classes exist to actually setup the certificate and be able +to enhance the configuration. (Turn on HSTS, redirect to HTTPS, +etc). You can indicate your abilities through the +:meth:`~.IInstaller.supported_enhancements` call. We currently only +have one Installer written (still developing), `~.ApacheConfigurator`. + +Installers and Authenticators will oftentimes be the same +class/object. Installers and Authenticators are kept separate because +it should be possible to use the `~.StandaloneAuthenticator` (it sets +up its own Python server to perform challenges) with a program that +cannot solve challenges itself. (I am imagining MTA installers). + + +Display +~~~~~~~ + +We currently offer a pythondialog and "text" mode for displays. I have +rewritten the interface which should be merged within the next day +(the rewrite is in the revoker branch of the repo and should be merged +within the next day). Display plugins implement +`~letsencrypt.client.interfaces.IDisplay` interface. + + +Augeas +------ + +Some plugins, especially those designed to reconfigure UNIX servers, +can take inherit from `~.AugeasConfigurator` class in order to more +efficiently handle common operations on UNIX server configuration +files. + + +.. _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: + +.. code-block:: shell + + cd docs + make clean html SPHINXBUILD=../venv/bin/sphinx-build + +This should generate documentation in the ``docs/_build/html`` +directory. diff --git a/docs/index.rst b/docs/index.rst index b290b2231..34615168c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Welcome to the Let's Encrypt client documentation! intro using - project + contributing .. toctree:: :maxdepth: 1 diff --git a/docs/project.rst b/docs/project.rst deleted file mode 100644 index 421f0b062..000000000 --- a/docs/project.rst +++ /dev/null @@ -1,5 +0,0 @@ -================================ -The Let's Encrypt Client Project -================================ - -.. include:: ../CONTRIBUTING.rst diff --git a/docs/using.rst b/docs/using.rst index 9b09833e4..362b75d81 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -21,30 +21,30 @@ In general: Ubuntu ------ -:: +.. code-block:: shell - sudo apt-get install python python-setuptools python-virtualenv python-dev \ - gcc swig dialog libaugeas0 libssl-dev libffi-dev \ - ca-certificates + sudo apt-get install python python-setuptools python-virtualenv python-dev \ + gcc swig dialog libaugeas0 libssl-dev libffi-dev \ + ca-certificates .. Please keep the above command in sync with .travis.yml (before_install) Mac OSX ------- -:: +.. code-block:: shell - sudo brew install augeas swig + sudo brew install augeas swig Installation ============ -:: +.. code-block:: shell - virtualenv --no-site-packages -p python2 venv - ./venv/bin/python setup.py install - sudo ./venv/bin/letsencrypt + virtualenv --no-site-packages -p python2 venv + ./venv/bin/python setup.py install + sudo ./venv/bin/letsencrypt Usage @@ -52,7 +52,7 @@ Usage The letsencrypt commandline tool has a builtin help: -:: +.. code-block:: shell ./venv/bin/letsencrypt --help