Refactor README into Docs

[bojanderson]

Closes #407

@marksweb I'm new to Open Source and GitHub, so if I created this too early let me know. I created this because my understanding is a "Draft" Pull Requests allow me to keep working on the issue and add commits, while still being able to get feedback.

Here's the checklist I'm planning on working on, if there's more I should be doing let me know. Or if I'm totally off base then I appreciate being pointed in the right direction.

• Created .rst files for different sections from README.rst
• Use Sphinx to create HTML
• Populate Index
• Update README.rst and remove redundant documentation

[marksweb]

Hey @bojanderson looks like you're doing great so far. I like this checklist approach to a PR.

If you were contributing to various projects doing this would certainly help keep track of where you were up to. I approve 👍

And it looks like you've started in the right direction by branching from the docs branch which Chris put some very basic sphinx config on back in 2016.

If you feel like anything could be improved by changing the formatting, an example maybe being the tables, which aren't very easy to maintain and I think there's a different format you can use for them. Feel free to try it out.

[bojanderson]

@marksweb I updated my comment, I believe I'm done with all 4 things that needed done. You can check out the commits I made and view the documentation here

I can mark the PR as ready for review if you think I'm ready.

[marksweb]

@bojanderson Nearly there. The build directory needs excluding from git though because these files are generated.

There's a really good example python .gitignore file here which includes an entry for sphinx; https://github.com/github/gitignore/blob/f651f0d3/Python.gitignore#L67-L68

So you'll need to use git rm.

If you want to remove the file from the Git repository and the filesystem, use:

git rm build/_docs
git commit -m "remove generated docs"

But if you wanted to remove the file only from the Git repository and not remove it from the filesystem, use:

git rm --cached file1.txt
git commit -m "remove file1.txt"

And to push changes to remote repo

git push origin branch_name

As a nice illustrative example, here's a screen shot from another of my projects django-bleach. As you can see, the docs/_build directory is excluded from git bit the other parts of the docs directory are committed.

[bojanderson]

@marksweb I removed the docs/_build directory like you requested along with a couple duplicate files that went in the repo directory.

However I'll admit I don't really understand the point of Sphinx if we don't include the HTML files in the repo. I looked at your django-bleach repo and I didn't see any HTML files, so I assume I have it the way you want it... I haven't used Sphinx before so I thought the value was it would create HMTL documentation we'd include in the repo. I'm sure it's the right call, I just find it confusing as somebody new to this.

[marksweb]

Ah ok, so the html files are generated based on the .rst files by sphinx. Therefore you don't check them into git, because the .rst files are the important part. You just use sphinx to generate the HTML at the point it's needed.

Another example of this is CSS and JS files. You can use node to build a gulp pipeline which takes your SASS/SCSS and javascript and compiles it/minifies it/etc at the point you build your containers or deploy to your web server, or packages your application for pypi. You don't want to store the compiled files in git, because they're just generated at the point you require them to make your application function.

Actually, I might build such a pipeline for this project because we've got a js file which is served un-minified.

So, with sphinx docs, you might register with read the docs which you link to your repo & when you commit changes, it will build the docs (HTML) for people to read.

[bojanderson]

@marksweb I have marked this as ready to review. Let me know your thoughts.