-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Built basic docs structure using ReadTheDocs #63
Conversation
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>
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
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. |
Signed-off-by: Max von Hippel <maxvonhippel1996@gmail.com>
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
<#63 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AEOeMivf6_GzJpzI4lSDrGdp9qCs54wUks5rSFLHgaJpZM4LjhWK>.
|
@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
And open
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
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 |
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. |
@argiopetech thanks! yes, readthedocs will build the documentation itself. From the readthedocs docs:
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.) |
Signed-off-by: Max von Hippel <maxvonhippel1996@gmail.com>
.... 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 🥇 |
Works for me! |
Whoops... Merged! |
(I have class pretty soon but will probably get the readthedocs online component working tonight) |
Actually, way easier than I thought it would be! Check the docs out here! |
Awesome! |
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