Artman documentation (googleapis#355)

.circleci/config.yml

@@ -1,15 +1,6 @@
 ---
 version: 2.0
 jobs:
-  build:
-    docker:
-      - image: python:3.6
-    steps:
-      - run:
-          name: Hello world!
-          command: echo "Hello world!"
-    working_directory: /usr/src/artman/
-
   build_and_push_docker_image:
     working_directory: /usr/src/artman
     docker:
@@ -79,6 +70,18 @@ jobs:
       - store_artifacts:
           path: /artman/test/golden/actual_library_example.golden
 
+  docs:
+    docker:
+      - image: python:3.6
+    steps:
+      - checkout
+      - run:
+          name: Install nox.
+          command: pip install --upgrade nox-automation
+      - run:
+          name: Build the docs.
+          command: nox -e docs
+
   unit-python2.7:
     docker:
       - image: python:2.7
@@ -304,6 +307,7 @@ workflows:
       - unit-python3.4
       - unit-python3.5
       - unit-python3.6
+      - docs
       - smoke-csharp
       - smoke-go
       - smoke-java

README.rst

@@ -1,140 +1,48 @@
 Google API Artifact Manager
 ===========================
 
-Google API Artifact manager (artman) is a set of modules used to automate the
-creation of software artifacts related to APIS defined using `protobuf`_ IDL.
-
-artman is an extensible framework that is responsible for creating all artifacts
-related to an API including
-
-- distribution packages in all supported programming languages
-- generic documentation websites
-- language-specific documentation websites (javadoc, readthedocs, etc)
-
-from the protobuf source IDL and additional configuration in YAML files.
-
-.. _`protobuf`: https://github.com/google/protobuf
-
-
-Installation
-------------
-1. Optional: set up a virtualenv for your Python work. Choose one of
-   the following:
-
-   1. (recommended) `virtualenvwrapper`_ so you don't have to keep
-      track of where your virtualenv is on the filesystem:
-
-      .. code::
-
-         sudo pip install virtualenv virtualenvwrapper
-         mkvirtualenv --python=`which python3` artman
-
-      To use this virtual environment later:
-
-      .. code ::
-
-         workon artman
-
-   2. `virtualenv`_ in your current directory:
-
-      .. code::
-
-         sudo pip install virtualenv
-         virtualenv env
-         source env/bin/activate
-
-2. Install artman directly from pip:
-
-   .. code::
-
-      pip install googleapis-artman
-
-You may need root privileges if you are not installing inside of a virtualenv.
-This will make the ``artman`` command available on your system.
-
-.. _`virtualenvwrapper`: https://virtualenvwrapper.readthedocs.io/en/latest/
-.. _`virtualenv`: https://pypi.python.org/pypi/virtualenv
-
-
-Prerequisites
--------------
-1. Install `googleapis`_
-2. Install `toolkit`_
-3. Install Java
-4. Some languages may have additional dependencies; refer to the ``Dockerfile``
-   in this repository for canonical installation requirements.
-
-.. _`googleapis`: https://github.com/googleapis/googleapis
+Google API Artifact Manager (``artman``) is a program used to automate the
+generaton and publishing of API client libraries.
+
+In order to be consumed by artman, APIs require:
+
+  * A `Protocol Buffers`_ description of the API, specified using proto3
+    syntax.
+  * A `service configuration`_ stub. This is YAML configuration which
+    designates how the API is housed within Google's infrastructure.
+  * A GAPIC configuration. This provides extra information specific to
+    generating a client library.
+  * An artman configuration. This is the file artman uses as the entry point,
+    and it points to the previous items in this list.
+
+The artman tool is a wrapper around `toolkit`_; it takes the configuration
+enumerated above, normalizes it, and sends it to toolkit, which generates
+a client library on disk, and then artman performs some concluding cleanup.
+
+Client libraries produced in this way are executable "out of the box", and
+include basic reference documentation, and appropriate packaging and
+metadata files.
+
+.. _`Protocol Buffers`: https://developers.google.com/protocol-buffers/
+.. _`service configuration`: https://cloud.google.com/service-management/overview#service_configurations
 .. _`toolkit`: https://github.com/googleapis/toolkit
 
 
-Usage
------
-
-Before you can use artman, you will need a configuration file. You can run
-``configure-artman`` to create a simple configuration file.
-
-For building a GAPIC (the most common task), the usage looks like:
-
-.. code::
-
-    artman --api pubsub --language python
-
-Artman also takes a ``--publish`` argument to decide where to stage the
-code. Using ``--publish github`` will create a pull request on GitHub
-automatically.
-
-
-Python Versions
----------------
-
-artman is currently tested with Python 2.7, Python 3.4, Python 3.5,
-and Python 3.6.
-
-.. note::
-
-    The authors of this README are humans, and this is an exceptionally
-    easy spot to end up out of date.
-
-    Our ``nox.py`` and ``.circleci/config.yml`` files are the real source
-    of truth for what versions of Python we test against.
-
-
-Contributing
-------------
-
-Contributions to this library are always welcome and highly encouraged.
-
-See the `CONTRIBUTING`_ documentation for more information on how to get
-started.
-
-.. _`CONTRIBUTING`: https://github.com/googleapis/artman/blob/master/CONTRIBUTING.rst
-
-
-Versioning
-----------
-
-This library follows `Semantic Versioning`_
-
-It is currently in major version zero (``0.y.z``), which means that anything
-may change at any time and the public API should not be considered
-stable.
-
-.. _`Semantic Versioning`: http://semver.org/
-
-
-Details
--------
+Installing
+==========
 
-For detailed documentation of the modules in artman, please watch
-`DOCUMENTATION`_.
+If your goal is just to use ``artman`` (rather than contribute to it), a
+standard pip install is probably not the right thing; we recommend
+the use of `pipsi`_ instead.
 
-.. _`DOCUMENTATION`: https://googleapis-artman.readthedocs.org/
+View our `installation guide`_ to get going.
 
+.. _`pipsi`: https://github.com/mitsuhiko/pipsi
+.. _`installation guide`: https://googleapis-artman.readthedocs.io/latest/installing.html
 
-License
--------
+Documentation
+=============
 
-BSD - See `LICENSE`_ for more information.
+Documentation is available on `Read the Docs`_.
 
-.. _`LICENSE`: https://github.com/googleapis/artman/blob/master/LICENSE
+.. _`Read the Docs`: https://googleapis-artman.readthedocs.io/

docs/_static/custom.css

@@ -0,0 +1,16 @@
+@import url('https://fonts.googleapis.com/css?family=Roboto|Roboto+Mono');
+
+@media screen and (min-width: 1080px) {
+    div.document {
+        width: 1040px;
+    }
+}
+
+code.descname {
+    color: #4885ed;
+}
+
+th.field-name {
+    min-width: 100px;
+    color: #3cba54;
+}