Add Examples page using example.rst

[Schamnad]

I have built the feature on top of the latest master changes.

This is in continuation to pull request #14

Have added examples for the ccget script using an Gaussian09 output file. The input used has been provided, the output was too large to paste and has not been provided at the moment.

The files I added were the examples.rst and edited the contents.rst to contain the example tag. All other files were modified when I ran the make command.

Testing done: Opened and checked individual HTML files to see if any of the pages are broken on Chrome

To Do: Add examples where the scripts have been used in larger python scripts.

[langner]

Remove powerful.

[Schamnad]

Done.

[langner]

Why did you add Javascript and a TTF file?

Also: I realize building the docs is a little clunky currently. I have a branch where I'm testing using a webhook that would include the customization we need.

[Schamnad]

The Javasript and TTF files were added dynamically by the make command. The only two files that I manually added/modified were the examples.rst and contents.rst files. The rest were either changed/generated by the make command.
Have pushed another commit with the changes that you had requested.

[langner]

I see. Which version of sphinx are you using?

[Schamnad]

1.4

[langner]

Can you try 1.2 easily?

[Schamnad]

I downloaded the Sphinx v.1.2.3 and removed the Sphinx v.1.4 from my computer. When I tried to run make in the sphinx/ directory, I get this error.

cclib.github.io/sphinx$ make
Updating prod...
cd _build/cclib_prod; git checkout v1.3.2; git fetch --all --tags
HEAD is now at 39f9f54... Some more bumping and new DOI for v1.3.2
Fetching origin
cd _build/cclib_prod; find . -name ".pyc" -o -name "pycache" -delete
Updating dev...
cd _build/cclib_dev; git pull origin; git fetch --all --tags
Already up-to-date.
Fetching origin
cd _build/cclib_dev; find . -name ".pyc" -o -name "pycache" -delete
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.2.3
loading pickled environment... failed: 'module' object has no attribute 'Symbol'

Theme error:
no theme named 'sphinx_rtd_theme' found (missing theme.conf?)
Makefile:122: recipe for target 'html' failed
make: *** [html] Error 1

I searched online and installed the sphinx_rtd_theme by following the 'via packages' instruction here. The second method of using the theme in the above link is what's followed by cclib.github.io

$ pip install sphinx_rtd_theme
Downloading/unpacking sphinx-rtd-theme
Downloading sphinx_rtd_theme-0.1.9-py2-none-any.whl (693kB): 693kB downloaded
Downloading/unpacking sphinx>=1.3 (from sphinx-rtd-theme)
Downloading Sphinx-1.4.1-py2.py3-none-any.whl (1.6MB): 1.6MB downloaded

This by default installs Sphinx 1.4 which is what I am trying to avoid.

Any suggestions on how I may proceed?

[langner]

The sphinx_rtd_theme is already included in the cclib.github.io repo as a submodule. You can download it when in the cclib.github.io repository with the command git submodule update --init --recursive. Please try that and run make again.

[Schamnad]

I downloaded the submodule and ran the make command again. This time Sphinx v1.2.3 was utilized but still the following untracked files were created.

../_sources/examples.txt
../_static/fonts/Inconsolata-Regular.ttf
../_static/jquery-1.11.1.js
../_static/underscore-1.3.1.js
../examples.html
examples.rst

All apart from examples.rst were created by the make command. I have also dumped the make process logs on pastebin (link).

I searched in the entire repo for references to the two .js and ttf files but the search resulted in zero results. I am unable to figure out why these new js/ttf files are being created. I deleted these new files to see if any of the pages broke, but everything was as it was supposed to be.

As I see it, we can proceed in three ways:

1. We could keep these newly created js/ttf files in the main branch until we figure out why they are being created
2. I could omit these files while pushing my code as they don't seem to serve any purpose
3. You could copy and paste the examples.rst in your local branch and try running 'make'. If these new js/ttf files are not being created, you could push it yourself (if that would be acceptable)

[langner]

Let me try to do the same thing locally later today. In the longer term, we need a better way to manage these docs.

[langner]

So I don't get these files when I run locally (also using Sphinx 1.2.3). What's more, the resulting html on your branch (when you look at it locally) is slightly different that our version on cclib.github.io.

Perhaps, try starting from scratch - remove your local repo, clone your examples branch from scratch, update the submodule again and run make. These files might be leftover from the previous theme you had installed.

I guess we should switch to Sphinx 1.4 soon, but let's do one thing at a time.

One more thing: the examples page shows up at the bottom of the sidebar - could you put it under Tutorial or somewhere more reasonable?

[langner]

Closing this, will continue on top of Schamnad's work in #30.