Should we remove the docs/ folder from the template?

[merelcht]

Description

Sub-task of #2149

[stichbury]

My kneejerk response is that @astrojuanlu and I just revised the section in the tutorial about building docs, and we'd have to rewrite it 😆 I'd also argue that it subtly "reminds" project owners to create documentation as part of best-practice.

But, in truth, it's not much effort to do the rewrite, and I'm not convinced that reminder is particularly beneficial. We were planning to remove the contents of docs (conf.py and index.rst) for version 0.19, so really we were almost all the way to removing the folder. I do think we should retain instructions for how to use Sphinx should you want to add some docs but leave it to the reader to (a) remember to add docs and (b) make a folder for them.

For that reason, and for simplicity, I say +1 to let's take it out.

TL;DR

Advantages of retaining docs

• We don't have to rewrite a section of docs
• It's best-practice to add documentation; including a docs folder in a project makes it a more obvious task

Disadvantages of retaining docs

• After 0.19 it'll be an empty folder because we have restructured instructions to build conf.py and index.rst from scratch
• It's extra clutter and complexity in the project

[astrojuanlu]

As @stichbury said, rewriting that guide is not an issue at all.

I'm on the fence about this. Generally speaking about gh-2149, maybe we could have a more interactive workflow that lets users pick what parts of the default template they want. That discussion should happen there however.

About just retaining the docs directory, I think we don't need to have a Sphinx conf.py and index.rst there. Maybe a docs/ directory with a README.md indicating that this is where docs should live, and pointing to our guide on how to setup Sphinx, is a more lightweight approach. Or as part of our own efforts to find a better documentation tool (gh-2072), maybe we can nudge users to another tool. Or finally, we could offload all this to a plugin (gh-2075).

[merelcht]

Closing this in favour of the utility add-ons work:#2388