Enhancement: Consider using Sphinx and Read the Docs for documentation

[willingc]

It would be helpful to have the ability to locally render documentation. There's a lot of great content in the documentation that has already been done. Python and Django projects often use Sphinx to build documentation and Read The Docs to render the documentation.

[vubo]

Thank you, Carol. I created the project at Read The Docs: http://vms.readthedocs.org/

[willingc]

@vubo Nice! Good job taking the initiative to dig into Sphinx, restructuredText (rst), and Read The Docs.

Docs are really important for a healthy, productive project. It's one of the ways that developers share project knowledge and onboard new developers to a project.

Why don't you make a pull request to submit your work to this repo? I think it's great to build one's skills with git and GitHub as well as sharing your work with others on the project. Personally, I find it helpful to regularly (daily or a few times a week) submit code to a project.

The basic steps for a pull request are in the Systers' Portal project documentation. Here's a checklist of some generic steps and git commands that I use:

• [ ] Fork the project
• [ ] Clone it to your local development system git clone
• [ ] Set up your git remotes (origin and upstream) git remote -v git remote add <remote name> <url of remote repo> (Remotes can be confusing at first so please ask questions or if you want to chat on IRC about them) Note: you will only need to do this step once.
• [ ] Create a local branch for any new development git branch <feature branch name> and checkout the branch git checkout <feature branch name>
• [ ] Develop and commit changes to the local branch git add, git commit, git log, git status
• [ ] Get the most up to date version of the upstream code git fetch upstream
• [ ] Rebase your changes onto upstream git rebase upstream/master Use git log to check that your commit is the most recent.
• [ ] Push the changes to your GitHub repo git push origin <feature branch name>
• [ ] Go to your account in GitHub and submit the pull request :smile:

As an aside, git status is your friend. Use it often :wink:

While this might seem like a lot now, it's very helpful to have a consistent workflow since it keeps you organized and saves time and reduces errors in the long run.

cc/ @rosariorobinson @Nerdylicious @tapasweni-pathak and Suzanne (If someone has her GitHub user name, please add in a comment. Thanks.

[vubo]

@willingc, thank you very much for the detailed instructions. I will follow them! I have already fulfilled many of them, but a few are still waiting their turn ("rebase" for example).

Read The Docs also supports Markdown docs written with Mkdocs. And the documentation for VMS is written in Git Flavored Markdown. And now I'm just published our documentation on the Read The Docs. Nothing had to be changed and it looks nice.

Do you think, perhaps, we should continue to write documentation in Markdown? Or should we use the Sphinx? I'm not familiar with the Sphinx, so it's hard to decide for me.

Thank you!

[willingc]

@vubo Cool! I didn't realize that Mkdocs was supported in Read The Docs now. You've taught me something new :sun:

I'm going to leave the call on whether Markdown or restructuredText as well as the corresponding Mkdocs and Sphinx to @rosariorobinson and others. It would be nice to be consistent across projects, and she, along with others, have a better view of all the projects. Currently, Portal uses restructuredText and Sphinx.

As a bit of background on Sphinx, it's nice because it's widely used in the Python/Django communities and it can run some nice tests when building the docs.

I would still go ahead and make a pull request with the configuration file for Mkdocs and a new brief markdown file for the docs with some simple instructions if someone else wanted to use Mkdocs to build the docs locally.

I'm hoping creating the pull request will help you feel comfortable working with git and GitHub before we get into the more rigorous development part of the GSOC. I just want to make sure you have the tools and knowledge to be productive :)

[vubo]

@willingc, thank you! I did pull request with two commits: https://github.com/systers/vms/pull/14

Can I choose commits for the pull request? For example, only commit 87c15cb

[willingc]

@vubo Great! I left you a couple of comments on the PR.

A couple of tips...

1. If you mention the issue number in a comment or title of the pull request, GitHub will put a note in the issue that there is an outstanding pull request addressing the issue. See my comment in the PR and the note above.
2. It's good practice when making a Pull Request to have an issue opened for the change as well. If an issue doesn't already exist, you would file an issue with a brief summary of what feature/fix/action is needed. Then, you will file a pull request and reference the newly created issue. It's good practice because the pull request will then match an issue and it helps for maintainability and project history (especially when you look at something i.e. a bug months later).

Yes, you can choose commits for a pull request. In fact, I would recommend splitting the pull request into two pull requests. Remember git rebase and branches. I'm heading out for the day but would be willing to walk you through the process tomorrow. Here are a few resources if you want to give it a try: http://openhatch.readthedocs.org/en/latest/advanced/working_with_git.html and http://git-scm.com/docs and https://github.com/pydata/pandas/wiki/Using-Git

Keep up the good work! :penguin:

[willingc]

I'm closing this issue since the current use of Read The Docs is serving the project well.