Merge pull request #213 from sarah256/docs

Refactor documentation to include README
redhat-exd-rebuilds · Oct 19, 2018 · f14c38a · f14c38a
2 parents 11aa009 + b0402b8
commit f14c38a
Show file tree

Hide file tree

Showing 11 changed files with 30 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,10 @@
-# Estuary API and Scrapers
+# Getting Started
+
+## Overview
+
+Estuary visualizes the story an artifact takes in the Red Hat build to release pipeline,
+with a focus on the automation of container rebuilds due to CVEs. This repository contains
+the API and scrapers for the [Estuary front end](https://github.com/release-engineering/estuary).
 
 ## Development
 

diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -1,3 +1,5 @@
 -r requirements.txt
 -r scraper-requirements.txt
-sphinx
+recommonmark
+sphinx
+sphinx_rtd_theme
diff --git a/docs/README.md b/docs/README.md
@@ -3,9 +3,9 @@
 
 ## Installing Sphinx
 
-The documentation runs on Sphinx.  To install it, run the following command **in a virtualenv**:
+The documentation is built with Sphinx.  To install it along with the documentation's other dependencies, run the following command **in a virtualenv**:
 ```
-$ pip install -U sphinx
+$ pip install -r docs-requirements.txt
 ```
 
 ## Build the Docs

diff --git a/docs/conf.py b/docs/conf.py
@@ -64,8 +64,8 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
 
 # The master toctree document.
 master_doc = 'index'

diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -9,12 +9,11 @@ Welcome to Estuary API's documentation!
 =======================================
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Contents
+   :maxdepth: 3
 
-   models
-   api
-   utils
-   scrapers
+   gettingstarted
+   module_documentation/index
 
 
 Indices and tables

diff --git a/docs/api.rst → docs/module_documentation/api.rst b/docs/api.rst → docs/module_documentation/api.rst
diff --git a/docs/module_documentation/index.rst b/docs/module_documentation/index.rst
@@ -0,0 +1,11 @@
+=====================
+Modules Documentation
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   models
+   scrapers
+   utils
diff --git a/docs/models.rst → docs/module_documentation/models.rst b/docs/models.rst → docs/module_documentation/models.rst
diff --git a/docs/scrapers.rst → docs/module_documentation/scrapers.rst b/docs/scrapers.rst → docs/module_documentation/scrapers.rst
diff --git a/docs/utils.rst → docs/module_documentation/utils.rst b/docs/utils.rst → docs/module_documentation/utils.rst