Merge pull request #3294 from certbot/docs-structure

New docs structure and introduction

docs/index.rst

@@ -5,9 +5,11 @@ Welcome to the Certbot documentation!
    :maxdepth: 2
 
    intro
+   install
    using
    contributing
    packaging
+   resources
 
 .. toctree::
    :maxdepth: 1

docs/install.rst

@@ -0,0 +1,33 @@
+=====================
+Quick Installation
+=====================
+
+If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS (visit
+certbot.eff.org_ to find out), you can install it
+from there, and run it by typing ``certbot`` (or ``letsencrypt``).  Because
+not all operating systems have packages yet, we provide a temporary solution
+via the ``certbot-auto`` wrapper script, which obtains some dependencies from
+your OS and puts others in a python virtual environment::
+
+  user@webserver:~$ wget https://dl.eff.org/certbot-auto
+  user@webserver:~$ chmod a+x ./certbot-auto
+  user@webserver:~$ ./certbot-auto --help
+
+.. hint:: The certbot-auto download is protected by HTTPS, which is pretty good, but if you'd like to
+          double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it::
+
+            user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc
+            user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2
+            user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto
+
+And for full command line help, you can type::
+
+  ./certbot-auto --help all
+
+``certbot-auto`` updates to the latest client release automatically.  And
+since ``certbot-auto`` is a wrapper to ``certbot``, it accepts exactly
+the same command line flags and arguments.  More details about this script and
+other installation methods can be found `in the User Guide
+<https://certbot.eff.org/docs/using.html#installation>`_.
+
+.. _certbot.eff.org: https://certbot.eff.org/

docs/intro.rst

@@ -1,6 +1,7 @@
 =====================
-README / Introduction
+Introduction
 =====================
 
 .. include:: ../README.rst
-.. include:: ../CHANGES.rst
+    :start-after: tag:intro-begin
+    :end-before: tag:intro-end

docs/resources.rst

@@ -0,0 +1,54 @@
+=====================
+Resources
+=====================
+
+Documentation: https://certbot.eff.org/docs
+
+Software project: https://github.com/certbot/certbot
+
+Notes for developers: https://certbot.eff.org/docs/contributing.html
+
+Main Website: https://letsencrypt.org/
+
+Let's Encrypt FAQ: https://community.letsencrypt.org/t/frequently-asked-questions-faq/26#topic-title
+
+IRC Channel: #letsencrypt on `Freenode`_ or #certbot on `OFTC`_
+
+Community: https://community.letsencrypt.org
+
+ACME spec: http://ietf-wg-acme.github.io/acme/
+
+ACME working area in github: https://github.com/ietf-wg-acme/acme
+
+
+Mailing list: `client-dev`_ (to subscribe without a Google account, send an
+email to client-dev+subscribe@letsencrypt.org)
+
+|build-status| |coverage| |docs| |container|
+
+
+
+.. |build-status| image:: https://travis-ci.org/certbot/certbot.svg?branch=master
+   :target: https://travis-ci.org/certbot/certbot
+   :alt: Travis CI status
+
+.. |coverage| image:: https://coveralls.io/repos/certbot/certbot/badge.svg?branch=master
+   :target: https://coveralls.io/r/certbot/certbot
+   :alt: Coverage status
+
+.. |docs| image:: https://readthedocs.org/projects/letsencrypt/badge/
+   :target: https://readthedocs.org/projects/letsencrypt/
+   :alt: Documentation status
+
+.. |container| image:: https://quay.io/repository/letsencrypt/letsencrypt/status
+   :target: https://quay.io/repository/letsencrypt/letsencrypt
+   :alt: Docker Repository on Quay.io
+
+.. _`installation instructions`:
+   https://letsencrypt.readthedocs.org/en/latest/using.html
+
+.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU
+
+.. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt
+.. _OFTC: https://webchat.oftc.net?channels=%23certbot
+.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev

docs/using.rst

@@ -5,6 +5,25 @@ User Guide
 .. contents:: Table of Contents
    :local:
 
+
+System Requirements
+===================
+
+The Let's Encrypt Client presently only runs on Unix-ish OSes that include
+Python 2.6 or 2.7; Python 3.x support will hopefully be added in the future. The
+client requires root access in order to write to ``/etc/letsencrypt``,
+``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to bind to ports 80 and 443
+(if you use the ``standalone`` plugin) and to read and modify webserver
+configurations (if you use the ``apache`` or ``nginx`` plugins).  If none of
+these apply to you, it is theoretically possible to run without root privileges,
+but for most users who want to avoid running an ACME client as root, either
+`letsencrypt-nosudo <https://github.com/diafygi/letsencrypt-nosudo>`_ or
+`simp_le <https://github.com/kuba/simp_le>`_ are more appropriate choices.
+
+The Apache plugin currently requires a Debian-based OS with augeas version
+1.0; this includes Ubuntu 12.04+ and Debian 7+.
+
+
 Getting Certbot
 ===============
 
@@ -13,7 +32,7 @@ visit certbot.eff.org_. This is the easiest way to learn how to get
 Certbot up and running on your system. 
 
 If you're offline, you can find some general
-instructions `in the README / Introduction <intro.html#installation>`__
+instructions under `Quick Installation <install.html>`__.
 
 __ installation_
 .. _certbot.eff.org: https://certbot.eff.org
@@ -564,3 +583,8 @@ Beyond the methods discussed here, other methods may be possible, such as
 installing Certbot directly with pip from PyPI or downloading a ZIP
 archive from GitHub may be technically possible but are not presently
 recommended or supported.
+
+.. include:: ../README.rst
+    :start-after: tag:features-begin
+    :end-before: tag:features-end
+.. include:: ../CHANGES.rst