PLOS
WIP: Docs
This PR includes documentation for how to get started with the starter corpus (renamed from 'seed') and explaining how the download_check_and_move() works in a 'docs' folder.
There are 2 docs, 1 in md and the other in rst, I suggest to consolidate in one markup type. I like rst but I can use any, have no strong feeling toward any, but I am for using only one. What about you?
Why would you prefer one markup type? I’m genuinely curious — I’m sure there are good reasons that I’m not thinking of.
I will say though one of the reasons I like Sphinx so much is that it makes it possible to use different document formats in a compatible manner (without too much overhead).
In my mind, different formats are more or less useful for different things. Markdown is better for lightweight documents. ReST is better when we need the power of such a generalized role system and automated document generation(via autodoc). I was planning on integrating nbsphinx and ipynb support once the docs had stabilized more (which makes for good tutorial docs).
As long as we set up Sphinx’s conf.py with correct extensions, it should run super smoothly (including cross references across formats).
If you want I can set this up for us. It just would help to have a bit more content to work with. I’m going to be working on docs for display_xml tomorrow, so it wouldn’t be hard to also include some docs infrastructure changes for allofplos.
The reason why I think one markup type will do it is because this is a small project. Do you want to use Rest?
If you don’t want to handle docs support, having a variety of doc formats is important to me so I’m happy to figure out the infrastructure.
I don’t think the size of a open source project should determine the quality of the docs.
I think that this is not a the complexity using and developing a code base is a better determinant of documentation decisions than the size of the codebase. It also isn’t particularly small, and it’s only getting bigger and more complex.
We’re going to need at least 4 different kinds of docs: contributor docs(explaining the design of the codebase), api docs (explaining how to use particular apis; mostly created from doc strings), expository user docs (how to set up and an overview of where to find different pieces of functionality), and tutorial docs (how to use the library in detail for a variety of tasks using the various features we have built in).
I want to use a mix of ReST and markdown for contributor docs, ReST for api docs, markdown for user docs and ipynb for tutorial docs.
I was not in favor of multiple doc formats if there were no need for it, but you made a case for multiple types of docs and it makes sense to me.
I absolutely agree that if there weren’t specific advantages to the different formats we should definitely not have multiple formats.
Good to hear we’re on the same page (both in particulars and in how we approach the problem).