FEAT: Questions to include/exclude/modify from the vanilla sphinx-quickstart module

[AakashGfude]

The default question list which sphinx has at the moment are mentioned below as task lists, to indicate which one should be kept.

NOTE: The fields/questions which require an input are written in bold

• [ ] 1) Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. Separate source and build directories (y/n)

@mmcky: I would vote for a default directory structure not customisable in Quickstart but rather via conf.py and detailed in docs of the structure and how to change it.

• [ ] 2) Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. Name prefix for templates and static dir []:

@mmcky: I would vote for a default templates and _static location

• [ ] 3) The project name will occur in several places in the built documentation. Project name: Author name(s): Project release[]:

@mmcky I think this is needed. Project release is probably the only confusing one for scientific publishing use case.

• [ ] 4) If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. Project language [en]:

@mmcky: I think we should remove this for now (as sphinxcontrib-jupyter doesn't support language sets)

• [ ] 5) The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. Source file suffix [.rst]:

• [ ] 6) One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. Name of your master document (without suffix) [index]:

@mmcky: I think this is a useful question but perhaps not necessary if we force index as the top level document.

• [ ] 7) Indicate which of the following Sphinx extensions should be enabled: autodoc: automatically insert docstrings from modules (y/n) [n]: doctest: automatically test code snippets in doctest blocks (y/n) [n]: intersphinx: link between Sphinx documentation of different projects (y/n) [n]: todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: coverage: checks for documentation coverage (y/n) [n]: imgmath: include math, rendered as PNG or SVG images (y/n) [n]: mathjax: include math, rendered in the browser by MathJax (y/n) [n]: ifconfig: conditional inclusion of content based on config values (y/n) [n]: viewcode: include links to the source code of documented Python objects (y/n) [n]: githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

@mmcky: I think this should be culled to the set of packages we have tested with sphinxcontrib-jupyter such as sphinxcontrib-bibtex. And then we can add more to the list as the needs or use grows.

• [ ] 8) A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. Create Makefile? (y/n) [y]: Create Windows command file? (y/n) [y]:

@mmcky: Let's put windows support on hold (as discussed in Slack) but writing the Makefile could be a default.

[mmcky]

hey @AakashGfude I am in favour of adopting a higher degree of defaults than what the standard sphinx Quickstart uses as I think many of our user base will just want to get up and running quickly rather than have the full flexibility of setting up the sphinx project in the way that they need or want. Th options can be adjusted in the conf.py file later on if they choose.

When we setup the docs for jupinx we should note what assumptions are made for things like a default directory structure etc.

Our own Questions

• [x] check that sphinxcontrib-jupyter is installed on the system and if not ask if the user would like to install it, add it to extensions in conf.py.

[jstac]

I agree on the need to cull options and also on favouring simplicity for the initial setup. Thanks guys.