writethedocs/docs — pull request #2 by benoitbryon (2013-01-25 15:54:48+00:00)
Title: Move documentation to "docs" folder

Here is a change proposal for the project structure.
It contains 2 commits:

* first commit moves current sphinx-powered files to a new docs/ folder
* second commit is a simple illustration of why I'm proposing that: added some project-centric stuff in root folder.

There are two main motivations:

* handle the repository as a project
* eat our own food, i.e. use this project as a live example

### Handle the repository as a project

... where documentation is just a part of it, even if it is the main part.

As an example, if we develop this project against a specific version of Sphinx (that's a point to discuss), some requirements.txt file is needed.

Also, we can add tests (check that the documentation builds or doctests pass), and more stuff which is not related to Sphinx and reStructuredText content.

That's why I propose to put things in a suitable place: docs in docs/ folder, configuration in etc/ folder, generated data in var/ folder... The root folder keeps clean and readable.

Consider the Makefile I added as a sample. I'm not a Makefile guru. My goal was just to show an example: it provides few targets that make things easier for developers. The Makefile encapsulates potential complexity related to deployment or build.
As an example, I used virtualenv. We can replace it with buildout or whatever we like, the Makefile usage won't change.

Usage of the sample Makefile:

```
git clone git@github.com:writethedocs/docs.git writethedocs
cd writethedocs/
make develop
make documentation
```

### Use this project as a live example

Most Python projects (I don't know about other technologies) can use the same layout:

* docs/ => documentation
* standard files like README, LICENSE...
* other stuff like setup.py, code...

We are dealing with recommendations about documentation content.
I guess we are to provide those two recommendations:

* at the root of the project, standard files like README, LICENSE, INSTALL, AUTHORS... are part of the documentation.
* in the (Sphinx) documentation, don't repeat yourself, include standard files like README from the root folder of your project.

In order to apply the recommendations above to writethedocs, I propose to have README, LICENSE... at the root of the project, then (sphinx-powered) documentation in docs/ folder. Just like any other (at least Python) project.