From 3fff631b32579ed1d3fa5b50349542b83dc62fda Mon Sep 17 00:00:00 2001 From: "Dylan J. Sather" Date: Wed, 25 Jan 2017 11:41:39 -0800 Subject: [PATCH] Expanded on documentation section, running through an example of committing a change to the docs end-to-end and describing the process for adding static assets (#2047) --- CONTRIBUTING.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1133cbe38651d..9fad927560390 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 git@github.com: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