Lots of doc cleanups

README.rst

@@ -31,14 +31,17 @@ Contributing
 If you'd like to contribute to this project please read `Developer Guide
 <https://certbot.eff.org/docs/contributing.html>`_.
 
+.. _installation:
+
 Installation
 ------------
 
-If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS, 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::
+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
@@ -188,3 +191,4 @@ Current Features
 .. _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
+.. _certbot.eff.org: https://certbot.eff.org/

certbot/cli.py

@@ -745,7 +745,8 @@ def prepare_and_parse_args(plugins, args, detect_defaults=False):
         " certificate lineage. You can try it with `--dry-run` first. For"
         " more fine-grained control, you can renew individual lineages with"
         " the `certonly` subcommand. Hooks are available to run commands "
-        " before and after renewal; see XXX for more information on these.")
+        " before and after renewal; see"
+        " https://certbot.eff.org/docs/using.html#renewal for more information on these.")
 
     helpful.add(
         "renew", "--pre-hook",

docs/contributing.rst

@@ -333,7 +333,7 @@ commands:
 
 .. code-block:: shell
 
-   make -C docs clean html
+   make -C docs clean html man
 
 This should generate documentation in the ``docs/_build/html``
 directory.

docs/intro.rst

@@ -1,6 +1,6 @@
-============
-Introduction
-============
+=====================
+README / Introduction
+=====================
 
 .. include:: ../README.rst
 .. include:: ../CHANGES.rst

docs/using.rst

@@ -5,56 +5,28 @@ User Guide
 .. contents:: Table of Contents
    :local:
 
-.. _installation:
+Getting Certbot
+===============
 
-Installation
-============
+To get specific instructions for installing Certbot on your OS, we recommend
+visiting certbot.eff.org_. If you're offline, you can find some general
+instructions `in the README / Introduction <intro.html#installation>`__
+
+__ installation_
+.. _certbot.eff.org: https://certbot.eff.org
 
 .. _certbot-auto:
 
-certbot-auto
-----------------
+The name of the certbot command
+-------------------------------
 
-``certbot-auto`` is a wrapper which installs some dependencies
-from your OS standard package repositories (e.g. using `apt-get` or
-`yum`), and for other dependencies it sets up a virtualized Python
-environment with packages downloaded from PyPI [#venv]_. It also
-provides automated updates.
-
-To install and run the client, just type...
-
-.. code-block:: shell
-
-   ./certbot-auto
-
-.. hint:: The Let's Encrypt servers enforce rate
-   limits on the number of certificates issued for one domain. It is recommended
-   to initially use the test server via `--test-cert` until you get the desired
-   certificates.
-
-Throughout the documentation, whenever you see references to
-``certbot`` script/binary, you can substitute in
-``certbot-auto``. For example, to get basic help you would type:
-
-.. code-block:: shell
-
-  ./certbot-auto --help
-
-or for full help, type:
-
-.. code-block:: shell
-
-  ./certbot-auto --help all
-
-
-``certbot-auto`` is the recommended method of running the Certbot
-client beta releases on systems that don't have a packaged version.  Debian,
-Arch Linux, Gentoo, FreeBSD, and OpenBSD now have native packages, so on those
-systems you can just install ``certbot`` (and perhaps
-``certbot-apache``).  If you'd like to run the latest copy from Git, or
-run your own locally modified copy of the client, follow the instructions in
-the :doc:`contributing`.  Some `other methods of installation`_ are discussed
-below.
+Many platforms now have native packages that give you a ``certbot`` or (for
+older packages) ``letsencrypt`` command you can run. On others, the
+``certbot-auto`` / ``letsencrypt-auto`` installer and wrapper script is a
+stand-in. Throughout the documentation, whenever you see references to
+``certbot`` script/binary, you should substitute in the name of the command
+that certbot.eff.org_ told you to use on your system (``certbot``,
+``letsencrypt``, or ``certbot-auto``).
 
 
 Plugins
@@ -275,17 +247,21 @@ Certbot is working hard on improving the renewal process, and we
 apologize for any inconveniences you encounter in integrating these
 commands into your individual environment.
 
+.. _command-line:
+
+Command line options
+====================
+
+Certbot supports a lot of command line options.  Here's the full list, from
+``certbot --help all``:
+
+.. literalinclude:: cli-help.txt
 
 .. _where-certs:
 
 Where are my certificates?
 ==========================
 
-First of all, we encourage you to use Apache or nginx installers, both
-which perform the certificate management automatically. If, however,
-you prefer to manage everything by hand, this section provides
-information on where to find necessary files.
-
 All generated keys and issued certificates can be found in
 ``/etc/letsencrypt/live/$domain``. Rather than copying, please point
 your (web) server configuration directly to those files (or create
@@ -391,7 +367,7 @@ give us as much information as possible:
   also might contain personally identifiable information)
 - copy and paste ``certbot --version`` output
 - your operating system, including specific version
-- specify which installation_ method you've chosen
+- specify which installation method you've chosen
 
 Other methods of installation
 =============================