Skip to content

Commit

Permalink
Expanded on documentation section, running through an example of comm…
Browse files Browse the repository at this point in the history
…itting a change to the docs end-to-end and describing the process for adding static assets (apache#2047)
  • Loading branch information
Dylan J. Sather authored and mistercrunch committed Jan 25, 2017
1 parent bfa2891 commit 3fff631
Showing 1 changed file with 104 additions and 2 deletions.
106 changes: 104 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,111 @@ If you are proposing a feature:
- Remember that this is a volunteer-driven project, and that
contributions are welcome :)

## Latest Documentation
## Documentation

Latest documentation and tutorial are available [here](http://airbnb.io/superset)
The latest documentation and tutorial are available [here](http://airbnb.io/superset).

Contributing to the official documentation is relatively easy, once you've setup
your environment and done an edit end-to-end. The docs can be found in the
`docs/` subdirectory of the repository, and are written in the
[reStructuredText format](https://en.wikipedia.org/wiki/ReStructuredText) (.rst).
If you've written Markdown before, you'll find the reStructuredText format familiar.

Superset uses [Sphinx](http://www.sphinx-doc.org/en/1.5.1/) to convert the rst files
in `docs/` to the final HTML output users see.

To make changes to the rst files and build the docs using Sphinx, you'll need to install
a handful of developer dependencies. This will likely involve installing more than you'll
need to *just* edit the documentation, but it shouldn't take much work.

First, since Superset uses the [mysqlclient](https://pypi.python.org/pypi/mysqlclient)
package, you'll have to install some of the MySQL development files. If you're running
Mac OS X, you can use [Homebrew](http://brew.sh/) to install these:

brew install mysql-connector-c

If you're running Linux or Unix, use your package manager to install the MySQL dev
packages, e.g. on Ubuntu:

sudo apt-get install libmysqlclient-dev

Before you start changing the docs, you'll want to
[fork the Superset project on Github](https://help.github.com/articles/fork-a-repo/).
Once that new repository has been created, clone it on your local machine:

git clone [email protected]:your_username/superset.git

At this point, you may also want to create a
[Python virtual environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
to manage the Python packages you're about to install:

virtualenv superset-dev
source superset-dev/bin/activate

Finally, install the required Python dependencies by running this command
from the root of the Superset code that you checked out above:

cd superset
pip install -r dev-reqs.txt

To get the feel for how to edit and build the docs, let's edit a file, build
the docs and see our changes in action. First, you'll want to
[create a new branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
to work on your changes:

git checkout -b changes-to-docs

Now, go ahead and edit one of the files under `docs/`, say `docs/tutorial.rst`
- change it however you want. Check out the
[ReStructuredText Primer](http://docutils.sourceforge.net/docs/user/rst/quickstart.html)
for a reference on the formatting of the rst files.

Once you've made your changes, run this command from the root of the Superset
repo to convert the docs into HTML:

python setup.py build_sphinx

You'll see a lot of output as Sphinx handles the conversion. After it's done, the
HTML Sphinx generated should be in `docs/_build/html`. Go ahead and navigate there
and start a simple web server so we can check out the docs in a browser:

cd docs/_build/html
python -m SimpleHTTPServer

This will start a small Python web server listening on port 8000. Point your
browser to [http://localhost:8000/](http://localhost:8000/), find the file
you edited earlier, and check out your changes!

If you've made a change you'd like to contribute to the actual docs, just commit
your code, push your new branch to Github:

git add docs/tutorial.rst
git commit -m 'Awesome new change to tutorial'
git push origin changes-to-docs

Then, [open a pull request](https://help.github.com/articles/about-pull-requests/).

If you're adding new images to the documentation, you'll notice that the images
referenced in the rst, e.g.

.. image:: _static/img/tutorial/tutorial_01_sources_database.png

aren't actually included in that directory. _Instead_, you'll want to add and commit
images (and any other static assets) to the _superset/assets/images_ directory.
When the docs are being pushed to [airbnb.io](http://airbnb.io/superset/), images
will be moved from there to the _\_static/img_ directory, just like they're referenced
in the docs.

For example, the image referenced above actually lives in

superset/assets/images/tutorial

Since the image is moved during the documentation build process, the docs reference the
image in

_static/img/tutorial

instead.

## Setting up a Python development environment

Expand Down

0 comments on commit 3fff631

Please sign in to comment.