Built basic docs structure using ReadTheDocs

[maxvonhippel]

I’m using reST (http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#colored-boxes-note-seealso-todo-and-warnings) and ReadTheDocs (http://readthedocs.org/) to build editable docs for this project. Edit any .rst in base/docs/source and then run build html in base/docs to update accordingly.

Signed-off-by: Max von Hippel maxvonhippel1996@gmail.com

[maxvonhippel]

If you accept this PR, I can then proceed to connect the URL to the ReadTheDocs website and they'll automatically render it on their site. Here is an example from another project of how that looks. But you can also navigate in the PR to

base/docs/build

And open index.html in your browser of choice to get an idea of how the docs currently look.

All of the information from the original docs are in the ReadTheDocs docs I made, except one image from Xcode which I can add. Everything is clean and well-formatted. There are design choices to be made around what to italicize, embolden, etc. but I didn't think I should go to the trouble of formatting the minutiae until @argiopetech & @tedvh reply with their editing style choices / instructions for how to make it look.

Anyway check out the index.html and see what you think. I think it's pretty cool, and the major upside of this is that it makes it super easy to modify and update the docs whenever we want.

EDIT: just pushed an additional commit including the above-mentioned Xcode image, so now everything in the .pdf documentation also exists in the ReadTheDocs doc.

[tedvh]

Hi Max -

squid stuff looks good. What website do I go to in order to see the BASE-9 docs?

On 1/14/17 4:44 AM, Max von Hippel wrote:

If you accept this PR, I can then proceed to connect the URL to the ReadTheDocs website and they'll automatically render it on their site. Here is an example http://squid-bot.readthedocs.io/en/latest/ from another project of how that looks. But you can also navigate in the PR to

base/docs/build

And open index.html in your browser of choice to get an idea of how the docs currently look.

All of the information from the original docs are in the ReadTheDocs docs I made, except one image from Xcode which I can add. Everything is clean and well-formatted. There are design choices to be made around what to italicize, embolden, etc. but I didn't think I should go to the trouble of formatting the minutiae until @argiopetech https://github.com/argiopetech & @tedvh https://github.com/tedvh reply with their editing style choices / instructions for how to make it look.

Anyway check out the index.html and see what you think. I think it's pretty cool, and the major upside of this is that it makes it super easy to modify and update the docs whenever we want.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/argiopetech/base/pull/63#issuecomment-272601700, or mute the thread https://github.com/notifications/unsubscribe-auth/AEOeMivf6_GzJpzI4lSDrGdp9qCs54wUks5rSFLHgaJpZM4LjhWK.

[maxvonhippel]

@tedvh sorry I was unclear. Here is how it works:

Let's call the directory of the project "base". If you navigate to base/docs, you find /build and /source. Go to

base/docs/build/html

And open index.html. On a Mac, you can do this in terminal with

open index.html

And on any other computer you can just double click on the file in your file browser/finder/etc. It will open in your default web browser and you'll see beautifully organized docs, totally configurable and editable! To change the docs, modify the respective *.rst in base/docs/source and then navigate to base/docs and run

build html

Once this pull request is accepted, if it is, I can then set up a web-hook on the www.readthedocs.org website, and the website will automatically host our docs online, so people can read the docs easily on the internet without having to download our project or anything. Alternatively, I can configure the project to build a Github Pages site automatically from our docs .html and update the page every time we change the .html and we can point to that Github Page with the DNS from your existing BASE9 webpage. Whatever hosting platform you prefer - Github Pages, www.readthedocs.org, or others I have not really looked into - we can make it automatically work with the readthedocs html compiling setup I've put together here.

[argiopetech]

This seems like a very clean way to do documentation. I like it! The ability to version control with the source makes me happy as well.

Will ReadTheDocs' website build the documentation itself? I prefer never to include build targets in the repository if possible. If not, or if we need the HTML pages to build a Github Pages site (assuming we want to go down that road, @tedvh?), I'm willing to compromise on this occasion and just merge this as is.

[maxvonhippel]

@argiopetech thanks! yes, readthedocs will build the documentation itself. From the readthedocs docs:

Sign up for an account on RTD, then log in. Visit your dashboard and click Import to add your project to the site. Fill in the name and description, then specify where your repository is located. ... Within a few seconds your code will automatically be fetched from your public repository, and the documentation will be built. Check out our Build Process page to learn more about how we build your docs, and to troubleshoot any issues that arise. ... If you want to keep your code updated as you commit, configure your code repository to hit our Post Commit Hooks. This will rebuild your docs every time you push your code. ... We support multiple versions of your code. You can read more about how to use this well on our Versions page.

So, if/once this is accepted, I (or you or anyone else) can hook up readthedocs and it will automatically build and host the documentation, and auto-update! (Therefore to answer your point, yes I/we can remove the built documentation.)

[maxvonhippel]

.... and I've taken out the built html. So it should now be clean, you can merge, and I can connect the readthedocs web hook so it auto-builds. Then once it's working and hosted on readthedocs.org, we can add that URL to the README and call it a day 🥇

[argiopetech]

Works for me!

[argiopetech]

Whoops... Merged!

[maxvonhippel]

(I have class pretty soon but will probably get the readthedocs online component working tonight)

[maxvonhippel]

Actually, way easier than I thought it would be! Check the docs out here!

[argiopetech]

Awesome!