Integrate auto-generating filter list & curves, statically in docs

[jaladh-singhal]

This PR serves the same purpose of PR #12 that uses Jinja templating to generate RST files (static doc pages) from the wsynphot filter data. Besides, in this I've enhanced code as per the python style and made sure that the ~78 facility pages are generated while building docs (instead of keeping them saved in docs/ by default).

Also the notebook that allows arbitrary selection of facility and instrument by using dropdowns (shared in early March) is embedded in it as it was embedded in the previous PR only.

Following is the purpose of changes/addition of 4 files in 1st commit:

1. conf.py:

   • Makes possible that rst pages are rendered as Jinja Template to generate content in rst by using data
   • Uses wsynphot to load filter data and passes it to context dictionary so that data variables can be identified while rendering templates
   • Auto-generates facility pages (RST files) for all ~78 facilities from a single RST file (serving as template for them), when docs are built in _facility_pages directory

2. filter-list.rst:

   • By using data passed, it displays a list of facilities and their corresponding instrument and no. of filters
   • Each facility name links to the individual facility page to access the filters present it
   • Each instrument name permalinks to that instrument present in individual facility page

3. facility_page.rst:

   • It is used to create individual facility page for all the facilities with filename = <facilty_name>.rst which is used to access the data related to that facility when rendering template code present in it
   • Each facility page contains filter list and curves belonging to it and they're even classified under instruments sections (if present)
   • It also makes possible to update all facility pages by updating only this single file

4. gitignore:

   • When docs are built, _facility_pages/ directory get created and is populated with RST pages of all individual facilities, which are required by Sphinx to build corresponding html pages for them. As we're deploying docs from a virtual machine (Travis or Azure), it won't be a problem. But when user will build them locally, then it is necessary to not let Git track those files that are just copies of facility_page.rst used only by Sphinx when building.

I've taken enough time to check & make sure that this code is building docs absolutely fine as needed. There may be some changes required in text appearing on docs since it's a subjective matter - so let me know.

[review-notebook-app]

Check out this pull request on ReviewNB: https://app.reviewnb.com/starkit/wsynphot/pull/23

Visit www.reviewnb.com to know how we simplify your Jupyter Notebook workflows.

[jaladh-singhal]

Oh I just checked, build is failing for job that build docs from python 2.7 because os.makedirs() I used in conf.py doesn't support exists_ok argument in python2.7. But it's good that job that build docs from python3.6 (from where we're deploying docs) successfully passes!

I can fix this for python 2.7 but I was lately thinking that if we don't need building docs from python 2.7, I can remove that from travis.yml. @wkerzendorf please tell me what should I do out of the two?

[wkerzendorf]

a few things left to do.

[wkerzendorf]

is that really necesary?

[jaladh-singhal]

Yes it is absolutely necessary. See, we're building a static documentation of a very large dataset (~4500 filters) so we need to distribute that data across different pages - for which we're putting them hierarchically as per the facilities they belong to. Since we need ~78 facility HTML pages, thus we have to provide Sphinx ~78 RST pages from which it can build HTML by rendering them differently using Jinja Template variables.

This is achieved by a single template file facility_page.rst as I explained in 1st comment. Think of _facilty_pages dir hence created, equivalent to _build dir which are solely generated & controlled by Sphinx while building docs, without requiring any user intervention. The only difference is _facilty_pages dir is created as a part of pre-build step immediately after command to build docs is given, and _build dir when rst is read & rendered. So they are more or less same which make sure that docs can be build, while at the same time they doesn't affect our repo (gitignored).

[wkerzendorf]

I understand this - I mean can you create them in the right directory

[jaladh-singhal]

What do you think is right directory?

We can't put them in _build or _template dir, Sphinx doesn't read files from them. We can't put them in _static dir i.e. meant for custom stylesheets and other static files (like images, etc.), not at all for storing .rst files. I've accounted all options then used it and it gives desired results.

Sphinx docs even say that, "Sphinx is highly customizable but that means all you can do with them is not documented". I understand what I've done, is quite new to grasp, but consider it as a customized way to achieve what we want to implement.

I might be missing something, could you please elaborate what wrong do you see in it?

[wkerzendorf]

it's not very new to grasp 😉 - you somehow create the files earlier and then move them - why not create them directly where they should live.

[wkerzendorf]

It should be fully py3 - no py27 necessary

[jaladh-singhal]

It should be fully py3 - no py27 necessary

OK I'm removing unnecessary build job that builds docs on python2.7 env from travis.

[jaladh-singhal]

The docs built by this PR are showcased at https://jaladh-singhal.github.io/wsynphot/

I'll make sure to update them with each commit I make - so they'll always be in latest state.

[jaladh-singhal]

This commit adds the filter-tables instead of placeholders (put earlier) in filter pages. I've also updated the gh_pages as per the new build docs which show filter tables.