Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reduce questions of sphinx-quickstart #4148

Closed
tk0miya opened this issue Oct 13, 2017 · 5 comments
Labels
Milestone

Comments

@tk0miya
Copy link
Member

@tk0miya tk0miya commented Oct 13, 2017

Problem

  • At present, sphinx-quickstart asks many questions. it's not "quick" start.

Expected results

Make it simple.

@tk0miya

This comment has been minimized.

Copy link
Member Author

@tk0miya tk0miya commented Oct 22, 2017

Now sphinx-quickstart asks following questions:

> Separate source and build directories (y/n) [n]:
> Name prefix for templates and static dir [_]:
> Project name:
> Author name(s):
> Project version []:
> Project release []:
> Project language [en]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> 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]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
@tk0miya

This comment has been minimized.

Copy link
Member Author

@tk0miya tk0miya commented Oct 22, 2017

My proposal:

Name prefix for templates and static dir [_]:

I wonder why is this really needed. I suppose our users does not modify this.
So I'd like to remove this question or whole of feature.

Source file suffix [.rst]:

Somebody might change the extensions, but almost people do not.
I think this question can be removed.

Name of your master document (without suffix) [index]:

This might be not changed by default also.

Do you want to use the epub builder (y/n) [n]:

Nowadays EPUB is an one of commonly used documentation format.
And the builder becomes enough stable at present.
So I think it's time to go it as default builder.

Create Makefile? (y/n) [y]:
Create Windows command file? (y/n) [y]:

It's okay to generate these build scripts by default.

imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
mathjax: include math, rendered in the browser by MathJax (y/n) [n]:

math directive and role are built into docutils since 0.8.
So I think they are also built into Sphinx by default.
I know we have some choices of equation renderers for HTML builder.
Hence we should improve it as pluggable.

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]:
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]:

I propose you that all extensions are enabled by command-line-options only.
They are certainly useful, but I think its usecase is advanced usage and uncommon.

@jfbu

This comment has been minimized.

Copy link
Contributor

@jfbu jfbu commented Oct 24, 2017

I propose you that all extensions are enabled by command-line-options only.
They are certainly useful, but I think its usecase is advanced usage and uncommon.

Will they still be present in conf.py in commented out form?

@tk0miya

This comment has been minimized.

Copy link
Member Author

@tk0miya tk0miya commented Oct 26, 2017

There is only one config value for bundled extensions; todo_inculde_todos.
IMO, it is not needed when todo extension disabled.

@tk0miya tk0miya added this to the 2.0.0 milestone Sep 5, 2018
@tk0miya tk0miya closed this in 5365349 Feb 16, 2019
tk0miya added a commit that referenced this issue Feb 16, 2019
Closes #4148: quickstart: some questions are removed
@PhySci

This comment has been minimized.

Copy link

@PhySci PhySci commented Aug 9, 2019

Current 'Getting Started' page was not updated and does not reflect new short list of questions. Spent a couple hours figuring out what's going wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.