update README.md to point to the original documentation, as well as explain the current project status

[robdennis]

When 5.0.0 is put on pypi, it's reasonable to expect that people would like to start using the github repo as a reference, and if that's the case, the README file should have the appropriate information to support that.

[EliAndrewC]

So the GitHub wiki actually supports reStructuredText as a format, so I went ahead and just directly copy/pasted the existing "configobj.txt" into the wiki and it doesn't look too bad, though the custom stylings have been lost: https://github.com/DiffSK/configobj/wiki

In my opinion, done for this ticket means making the following changes:

• edit the wiki page in the following ways:

-- change the current version to 5.0.0

-- add the latest (5.0.0) version to the changelog

-- change Google Code links to point to Github instead

-- change the homepage to point to Github instead of voidspace

-- change Authors to list Rob and Eli alongside the original authors

-- update Date, or perhaps remove it completely, since as a wiki it's easy for people to see that without it needing to be posted

• add validate.py doc to wiki as well, which is also reStructuredText and make all of the same changes listed above to it as well
• edit the Github README file to point to the wiki and perhaps also have some usage examples

We need to decide whether it's worth keeping the wiki alongside the reStructuredText files which are under source control. The advantage to keeping the source control files as canonical is that we can use them to generate HTML, which can be uploaded elsewhere. For instance, we could upload the configobj stuff to http://pythonhosted.org/ and point there, since that will use the custom stylings which are checked into source control.

Assuming we want to do that, then it might be better to just make the changes in source control and not even use the wiki, and instead just upload things to pythonhosted.org since that'll look nicer than the wiki looks. Other people can't edit the docs as easily as they can edit a wiki, although they can still issue pull requests.

Any thoughts?

[robdennis]

I'm actually in favor of people editing the docs via pull requests since
it's already true that in my mind the docs are versioned alongside the
application.
I see the way forward as uploading it to pythonhosted or readthedocs and
pointing to that from the readme. Aside from that link and links to travis,
etc, the readme would only for simple usage examples.

On Mon, Feb 3, 2014 at 9:44 PM, Eli Courtwright notifications@github.comwrote:

So the GitHub wiki actually supports reStructuredText as a format, so I
went ahead and just directly copy/pasted the existing "configobj.txt" into
the wiki and it doesn't look too bad, though the custom stylings have been
lost: https://github.com/DiffSK/configobj/wiki

In my opinion, done for this ticket means making the following changes:

• edit the wiki page in the following ways: -- change the current
  version to 5.0.0 -- add the latest (5.0.0) version to the changelog --
  change Google Code links to point to Github instead -- change the homepage
  to point to Github instead of voidspace -- change Authors to list Rob and
  Eli alongside the original authors -- update Date, or perhaps remove it
  completely, since as a wiki it's easy for people to see that without it
  needing to be posted
• add validate.py doc to wiki as well, which is also reStructuredText
  and make all of the same changes listed above to it as well
• edit the Github README file to point to the wiki and perhaps also
  have some usage examples

We need to decide whether it's worth keeping the wiki alongside the
reStructuredText files which are under source control. The advantage to
keeping the source control files as canonical is that we can use them to
generate HTML, which can be uploaded elsewhere. For instance, we could
upload the configobj stuff to http://pythonhosted.org/ and point there,
since that will use the custom stylings which are checked into source
control.

Assuming we want to do that, then it might be better to just make the
changes in source control and not even use the wiki, and instead just
upload things to pythonhosted.org since that'll look nicer than the wiki
looks. Other people can't edit the docs as easily as they can edit a wiki,
although they can still issue pull requests.

Any thoughts?

Reply to this email directly or view it on GitHubhttps://github.com//issues/8#issuecomment-34025680
.

[EliAndrewC]

Sounds good to me. That's the way I was also leaning, so I'll go ahead and make that happen sometime in the next few days.

[EliAndrewC]

What version are we giving to validate? Its docs currently say 1.0.1 so I assume we're bumping to 2.0.0?

Really validate probably shouldn't have a separate version, so maybe we just bump it to 5.0.0 or something.

[robdennis]

Yeesh, I guess so

On Tue, Feb 4, 2014 at 5:34 PM, Eli Courtwright notifications@github.com
wrote:

What version are we giving to validate? Its docs currently say 1.0.1 so I assume we're bumping to 2.0.0?

Reply to this email directly or view it on GitHub:
#8 (comment)

[robdennis]

@EliAndrewC is between computers right now, so I'm grabbing this, with his eyes on the pull request before we tag.

I don't think we need to block on tagging before it gets onto pythonhosted but we'll see

[EliAndrewC]

Ok, I'm using an old Windows XP laptop to surf the internet, so I'm able to at least look at things and make comments, even if I don't have any kind of dev environment. I was hoping my new laptop would have arrived in the mail by now, but I haven't even gotten a notification that it's shipped - I'll try calling them today.

My plan for uploading to pythonhosted was basically to write the docs with links to http://pythonhosted.org/configobj/ since we know that will be the URL. Then after using docutils to generate the documentation, rename configobj.html to index.html and upload the resulting directory via PyPI.

We should probably wait to tag before doing this, since we ARE dropping support for several older versions. Anyone downloading as part of their build process SHOULD be pinning to a specific version, but it wouldn't surprise me if a few people had their Jenkins/Travis/whatever jobs start failing because they're still on Python 2.5 and are just downloading the latest, so it would be nice if the documentation explained what was happening. (Or we could decide that those people deserve to be punished, which I wouldn't have a real problem with.)

[robdennis]

I looked into this a fair bit on Friday and here are some findings:- there's a separate validate pypi index page which I don't have ownership for

• the validate docs point to that , and since it is packaged separately that's a motivation to not tie versions together
• I feel good about the rst content changes that I've made locally and I have the readtgedocs account all made a ready for it

Currently blocking on Michael Foord weighing in if he wants validate packaged separately still, and if we want to take that on. Once I know what we're going to do, we can edit the docs

On Sun, Feb 9, 2014 at 12:44 PM, Eli Courtwright notifications@github.com
wrote:

Ok, I'm using an old Windows XP laptop to surf the internet, so I'm able to at least look at things and make comments, even if I don't have any kind of dev environment. I was hoping my new laptop would have arrived in the mail by now, but I haven't even gotten a notification that it's shipped - I'll try calling them today.
My plan for uploading to pythonhosted was basically to write the docs with links to http://pythonhosted.org/configobj/ since we know that will be the URL. Then after using docutils to generate the documentation, rename configobj.html to index.html and upload the resulting directory via PyPI.

We should probably wait to tag before doing this, since we ARE dropping support for several older versions. Anyone downloading as part of their build process SHOULD be pinning to a specific version, but it wouldn't surprise me if a few people had their Jenkins/Travis/whatever jobs start failing because they're still on Python 2.5 and are just downloading the latest, so it would be nice if the documentation explained what was happening. (Or we could decide that those people deserve to be punished, which I wouldn't have a real problem with.)

Reply to this email directly or view it on GitHub:
#8 (comment)

[robdennis]

Which one do we want? Read the docs or python hosted or both?

On Sun, Feb 9, 2014 at 12:44 PM, Eli Courtwright notifications@github.com
wrote:

Ok, I'm using an old Windows XP laptop to surf the internet, so I'm able to at least look at things and make comments, even if I don't have any kind of dev environment. I was hoping my new laptop would have arrived in the mail by now, but I haven't even gotten a notification that it's shipped - I'll try calling them today.
My plan for uploading to pythonhosted was basically to write the docs with links to http://pythonhosted.org/configobj/ since we know that will be the URL. Then after using docutils to generate the documentation, rename configobj.html to index.html and upload the resulting directory via PyPI.

We should probably wait to tag before doing this, since we ARE dropping support for several older versions. Anyone downloading as part of their build process SHOULD be pinning to a specific version, but it wouldn't surprise me if a few people had their Jenkins/Travis/whatever jobs start failing because they're still on Python 2.5 and are just downloading the latest, so it would be nice if the documentation explained what was happening. (Or we could decide that those people deserve to be punished, which I wouldn't have a real problem with.)

Reply to this email directly or view it on GitHub:
#8 (comment)

[EliAndrewC]

pythonhosted.org looks simpler but less powerful. We need to manually upload a zipfile every time we want to update the docs, whereas at a glance it looks like readthedocs.org would let us automatically have the docs updated every time we push to GitHub.

I'm personally fine with the simpler pythonhosted.org option because I don't forsee the docs changing very much, given that configobj is a such a mature, stable product.

I didn't realize that validate had its own PyPI page; I'd assumed it was installed alongside configobj so I figured we'd just upload it alongside configobj so that it would be available at http://pythonhosted.org/configobj/validate.html and we could link to that when needing to link to the validate docs.

But if there's a separate PyPI package, we should probably get added as owners of that as well so that we can update it appropriately.

[robdennis]

I'm pro updated docs on push, and fwiw I feel like I did all the work on rtd already, so pending validate I'll maybe finish it out

On Sun, Feb 9, 2014 at 4:10 PM, Eli Courtwright notifications@github.com
wrote:

pythonhosted.org looks simpler but less powerful. We need to manually upload a zipfile every time we want to update the docs, whereas at a glance it looks like readthedocs.org would let us automatically have the docs updated every time we push to GitHub.
I'm personally fine with the simpler pythonhosted.org option because I don't forsee the docs changing very much, given that configobj is a such a mature, stable product.
I didn't realize that validate had its own PyPI page; I'd assumed it was installed alongside configobj so I figured we'd just upload it alongside configobj so that it would be available at http://pythonhosted.org/configobj/validate.html and we could link to that when needing to link to the validate docs.

But if there's a separate PyPI package, we should probably get added as owners of that as well so that we can update it appropriately.

Reply to this email directly or view it on GitHub:
#8 (comment)

[EliAndrewC]

If you've already done the work for ReadTheDocs then that does sound like a better solution. If we've got update on push working, then I think we should avoid using pythonhosted.org since then we'll have two sources of documentation, where one is potentially out of date.

[robdennis]

seems like #7 kind has become subsumed by this ticket, which is not the worst, but I need to catch up with @EliAndrewC in person on Monday