Change documentation generator to Sphinx

[pradyunsg]

This is an initial draft of the "new" documentation for Junction.

Some of the changes made:

• Add Sphinx support
• Break up instructions for installation
• python-dev and build-essential are unrelated to setting up the project-specific environment.
  • I have removed them for now but we can add them later.
• npm and NodeJS are installed together, no need to call them out separately.
  • bower and grunt get installed as we go, so no need to ask for them to be installed already.
• Move old documentation in an old/ directory
  • added a note to them, that they're old.

Making a PR early to get feedback on the changes.

---

Currently, the main "new" document is docs/source/development/getting-started.rst.

[pradyunsg]

Dependent on #576 being merged with CI fixes.

[coveralls]

Coverage remained the same at 67.28% when pulling 90148a1 on pradyunsg:sphinx into aaa1ca8 on pythonindia:master.

[coveralls]

Coverage remained the same at 67.28% when pulling 90148a1 on pradyunsg:sphinx into aaa1ca8 on pythonindia:master.

[coveralls]

Coverage increased (+0.05%) to 67.28% when pulling 344be6b on pradyunsg:sphinx into d3744d4 on pythonindia:master.

[pradyunsg]

I dropped the changes from #575 from this PR.

[zerothabhishek]

@pradyunsg how/where do we publish the docs ? Does Github run a build for Sphinx docs too ?

[pradyunsg]

Huh. I swear I remember responding to this.

I'll setup a readthedocs.org build for us, once this is merged.

[zerothabhishek]

@pradyunsg I'm trying a build and am running into failures. Here's what I did -

apt-get install python-sphinx  ## Python 2
pip install recommonmark
cd $PROJECT/docs
make html

And the error is:

File "/usr/lib/python2.7/dist-packages/sphinx/cmdline.py", line 244, in main
app.build(opts.force_all, filenames)
File "/usr/lib/python2.7/dist-packages/sphinx/application.py", line 267, in build
self.builder.build_update()
File "/usr/lib/python2.7/dist-packages/sphinx/builders/init.py", line 251, in build_update
'out of date' % len(to_build))
File "/usr/lib/python2.7/dist-packages/sphinx/builders/init.py", line 265, in build
self.doctreedir, self.app))
File "/usr/lib/python2.7/dist-packages/sphinx/environment.py", line 551, in update
self.doc2path(config.master_doc))
File "/usr/lib/python2.7/dist-packages/sphinx/environment.py", line 353, in doc2path
suffix = self.config.source_suffix[0]
KeyError: 0

Please send help 😕

[pradyunsg]

Uh, that'll probably install an old version of sphinx for you. Debian isn't exactly super fast in updating libraries.

I'd suggest building documentation using a virtualenv with the latest sphinx and recommonmark. This too can be added to the suggestions made in getting started in a subsequent PR.

We could even look for into adding automation for common development processes later.

[pradyunsg]

Poking this again. If there's no interest in this, I'll be happy to tackle this at a later time.

[zerothabhishek]

Hey @pradyunsg lets take it up after a few weeks .. currently busy with other tasks in CFP

[pradyunsg]

Works for me!