GSoC Diaries 4.01: Bringing everything together
We are already more than halfway through the third and final coding phase of GSoC 2018. I have managed to successfully integrate the new Astropy tutorials theme with the existing Sphinx build process.
How to make the new build?
To make the Sphinx build of the Astropy tutorials with the new theme
git clone https://github.com/MananAgarwal/astropy-tutorials.git
git checkout new-theme
pip install sphinx-bootstrap-theme
Now you are all set to build the Astropy tutorials like you normally do i.e.
git submodule init
git submodule update
source activate tutorials
sudo make html
Voila! Astropy tutorials with the new theme are ready. ( If you are facing some error, most probably you just need to update nbconvert.)
Files related to the new sphinx-theme are added in a ‘themes’ folder inside tutorials. Static files like Astropy logo, banner background, stylesheet are added in the ‘_static’ folder. I have then linked these inside the conf.py file to override the default configurations.
html_theme_path = [path.abspath(path.join(path.dirname(__file__), ‘themes’))]
html_theme = ‘tutorials-theme’
All the HTML build configurations are in the theme.conf file except for the sidebar configurations which is in the conf.py file.
While implementing this I was challenged by a number of weird errors and learned a lot of things the hard way like the importance of virtual environments, compatibility of different packages, etc. Some of these errors that are worth pointing out as they might trouble other developers also are:
1. Build process fails due to some error in the tutorial
Some of the tutorials have code which is intended to give an error as the output. These are to explain the usage and syntax of different packages. nbconvert is used to take care of this so that instead of throwing an error and stopping the build process, they are added to the tutorial build as output.
This can be solved by updating the nbconvert to the latest release from its official GitHub repo.
$ git clone https://github.com/jupyter/nbconvert.git
$ cd nbconvert
$ pip install -e .
2. Module not found error (inside the virtual environment)
Build process fails because it was unable to find a module. If you try installing this module inside the virtual environment then it will throw an error stating that the module is already installed. Weird right. It is surprising to find that by default this build does *not* use the same python environment we are running sphinx in. This is because the nbconvert machinery depends on Jupyter kernels to create a separated environment to run each notebook.
To solve this Erik has added the feature to explicitly state the environment we want nbconvert to run in. Pull request
To use a specific environment, you will need to use the ``jupyter kernelspec`` or ``ipykernel install`` command to create a named kernel for your favored environment. Then pass it into sphinx using the ``NBCONVERT_KERNEL`` environment variable. Something like::
$ python -m ipykernel install — user — name astropy-tutorials — display-name “Python (astropy-tutorials)”
$ NBCONVERT_KERNEL=astropy-tutorials make html
You can also resolve this by simply installing the module globally outside the virtual environment.
With less than two weeks remaining in GSoC 2018, I am working on the Astropy Examples Gallery. Seems like I’ll be soon making a pull request!!