[OH-Dev] Mid-month check-in: Sat 3/17, 4PM Eastern / 1 PM Pacific

[Daniel Mizyrycki]

I am replying inline a couple of emails here as they relate.


On 03/16/2012 11:24 PM, Pam Selle wrote:
>  I want to work on this. Not right now, maybe not till next weekend,
>  but I do :)
Pam and everybody who'd like to move forward docs: There are a few wiki 
documents that are already translated to ReST and indexed, so what needs 
to be done is much easier now. Let's try to coordinate here for an IRC 
discussion. Who is interested?

>
>  On 03/15/2012 04:25 PM, Asheesh Laroia wrote:
>
>  Dear Devel folks,
>
>  <Exciting>
>
>  We have all this documentation hosted by readthedocs.org
>  <http://readthedocs.org>. Meanwhile, we also have all these
>  documentation pages hosted within the openhatch.org
>  <http://openhatch.org> wiki.
>
>  Since readthedocs makes creating previous/next links, and
>  subcategories, here is my thoughts for one good way to recategorize
>  the docs we do have:
.
>  It would be super cool to merge these into the Sphinx docs.
.
>  <http://openhatch.readthedocs.org/>. These are generated from the rst
>  files in docs/*. You can generate them locally, too -- see the
>  docs/generate_html.py file.

As a proof of concept, I am the attaching a patch that add sphinx 
indices to the existing docs in the repo. More about the pull request below.

On 03/22/2012 09:53 AM, Asheesh Laroia wrote:
> > Some suggestions
> >
> > * Move all documentation to /docs and possibly have a symlink to
> > docs (like README.rst) so they will be part of the official
> > documentation. (One caveat is that Sphinx and ReadTheDocs work as
> > expected as root for the documents is /docs, but github assumes
> > root at the project level, so links to repo documents do not render
> > correctly. We could point to ReadTheDocs to work around the issue,
> > but this adds a dependency :( )
>
>  Oh, Github.
>
>  So the thing about symlinks is that they don't seem to work on
>  Windows, even though git "supports" them, which leads to oddities. If
>  you can test that adding a symlink is fine for people on Windows who
>  clone the repo, that'd be great, but I remember problems before.
Do we have Windows users for our repo? Are any of our developers working
and supporting it?

>
>  I see now that we did make README.rst a symlink; I'm curious what
>  that does on Windows!
Anybody with a Windows computer can answer, please?

>
>  I would say yes, let's move all documentation to docs/, except leave
>  a README.rst that simply says, "For documentation, look in the docs/
>  directory."
I am tempted to do this.

>
>  As for Github linking, I would say let's make them work properly in
>  Sphinx first, and see if we can get Github to fix its parsing of
>  restructured text. In particular, I think their parsers for these
>  text formats are actually on the web and freely licensed, so it would
>  be quite possible to submit a pull request to them.
I think the issue is that a /README is very well accepted for package 
distribution.

>
> > * Add an authors.rst or/and contributors.rst file on the repo.
>
>  I like this idea. I'd say contributors.rst but whatever's most common
>  in rST-land.
I'll do some surveys on this.

> > Some people have shown interest to help with docs. How would you
> > like we move forward?
>
>  I would say:
>
>  * Discuss docs-related ideas on the mailing list and/or IRC
following up :-)

>
>  * Submit patches (with git format-patch, either to the mailing list
>  or a ticket) or pull requests (on Github.com)
proof of concept attached.

>  Given what we've seen so far, probably you'll prefer the Github pull
>  request route.
Yes

>  I'll rebase those to be against current origin/master,
>  sanity-check, and push!
Nice. I've got an issue though. I forked oh-mainline and before my 
previous pull
request I did "git pull --rebase upstream master" so my commits get 
added to the end
of the history, and keep master history linear. After the pull request 
got merged, plus some other commits, I tried to  "git pull --rebase 
upstream master" (this went well) and "git push" (back to my fork and got:
To git at github.com:mzdaniel/oh-mainline.git
  ! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to 'git at github.com:mzdaniel/oh-mainline.git'

After doing gitk, found that the history of oh-mainline is not linear. 
Any quick reference to a howto I can look at to push my changes for a 
proper pull request?

>
>  Does that seem like a usable workflow?
Yes. You mention creating a docs branch at some point. Do you still 
think is a good idea?
If yes, I am assuming that branch will be created in my fork and 
somebody will merge
it to master. Then, I just need to rebase my fork and recreate the doc 
branch for new
changes.

>
>  -- Asheesh. _______________________________________________ Devel
>  mailing list Devel at lists.openhatch.org
>  http://lists.openhatch.org/mailman/listinfo/devel
>


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openhatch.org/pipermail/devel/attachments/20120327/39468e65/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oh-docs.patch
Type: text/x-patch
Size: 49378 bytes
Desc: not available
URL: <http://lists.openhatch.org/pipermail/devel/attachments/20120327/39468e65/attachment-0001.bin>