You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@couchdb.apache.org by Dave Cottlehuber <dc...@jsonified.com> on 2012/09/26 23:02:22 UTC
couch has docs!
Hi,
After much hand-wringing & gnashing of teeth, we now have a /docs/
branch in git[1], [2], and available online [3]. A huge thank-you to
Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
this happen. The single biggest thing you can do as thanks, is to send
us improvements, in any form you feel comfortable, and in any size.
Sending in changes & fixes should be as easy as 1-2-3:
1: fork locally with git, or github
2: edit the .rst format [7] files either in the slick github UI, or in
your favourite editor
3: send a pull request, mail, jira, or a patch as you prefer
I hopefully documented those steps [4] so please let me know if it
works. Live Long & Document!
Notes & Tips:
- /docs/ lags master a wee bit, nothing serious
- feel free to use COUCHDB-1536 for tracking any integration work in
the /docs/ branch
- you can use pandoc online [5] to convert from your favourite format
- it looks like github lets you edit in markdown but send in changes
in rst format
[1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
[2]: https://github.com/apache/couchdb/tree/docs
[3]: http://couchdb.readthedocs.org/en/latest/index.html
[4]: http://wiki.apache.org/couchdb/Documentation
[5]: http://johnmacfarlane.net/pandoc/try
[6]: https://issues.apache.org/jira/browse/COUCHDB-1536
[7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
A+
Dave
Re: couch has docs!
Posted by Jens Alfke <je...@couchbase.com>.
On Sep 26, 2012, at 2:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3].
Oh, great. My hard-won knowledge of the API is now made easily available to any newbie who can read.
But seriously — congratulations to all involved! These look slick and well-organized. When I have more time I’ll browse through them and fill in missing bits that I find and have knowledge of.
—Jens
Re: couch has docs!
Posted by stephen bartell <sn...@gmail.com>.
This is huge! good job!
Stephen Bartell
"The significant problems we face cannot be solved at the same level of thinking we were at when we created them." -Einstein
On Sep 27, 2012, at 8:37 AM, Bob Dionne wrote:
> Bravo! They look nice. I still find the WIKI cool also but the search feature looks helpful.
>
> On Sep 26, 2012, at 5:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
>
>> Hi,
>>
>> After much hand-wringing & gnashing of teeth, we now have a /docs/
>> branch in git[1], [2], and available online [3]. A huge thank-you to
>> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
>> this happen. The single biggest thing you can do as thanks, is to send
>> us improvements, in any form you feel comfortable, and in any size.
>>
>> Sending in changes & fixes should be as easy as 1-2-3:
>>
>> 1: fork locally with git, or github
>> 2: edit the .rst format [7] files either in the slick github UI, or in
>> your favourite editor
>> 3: send a pull request, mail, jira, or a patch as you prefer
>>
>> I hopefully documented those steps [4] so please let me know if it
>> works. Live Long & Document!
>>
>> Notes & Tips:
>> - /docs/ lags master a wee bit, nothing serious
>> - feel free to use COUCHDB-1536 for tracking any integration work in
>> the /docs/ branch
>> - you can use pandoc online [5] to convert from your favourite format
>> - it looks like github lets you edit in markdown but send in changes
>> in rst format
>>
>> [1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
>> [2]: https://github.com/apache/couchdb/tree/docs
>> [3]: http://couchdb.readthedocs.org/en/latest/index.html
>> [4]: http://wiki.apache.org/couchdb/Documentation
>> [5]: http://johnmacfarlane.net/pandoc/try
>> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
>> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>>
>> A+
>> Dave
>
Re: couch has docs!
Posted by Bob Dionne <di...@dionne-associates.com>.
Bravo! They look nice. I still find the WIKI cool also but the search feature looks helpful.
On Sep 26, 2012, at 5:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
Re: couch has docs!
Posted by Jens Alfke <je...@couchbase.com>.
On Sep 26, 2012, at 2:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3].
Oh, great. My hard-won knowledge of the API is now made easily available to any newbie who can read.
But seriously — congratulations to all involved! These look slick and well-organized. When I have more time I’ll browse through them and fill in missing bits that I find and have knowledge of.
—Jens
Re: couch has docs!
Posted by Noah Slater <ns...@tumbolia.org>.
Thank you Dave. This is great work!!
On Wed, Sep 26, 2012 at 10:02 PM, Dave Cottlehuber <dc...@jsonified.com>wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]:
> https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
>
--
NS
Re: couch has docs!
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Wed, Sep 26, 2012 at 11:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
> - /docs/ lags master a wee bit, nothing serious
Do we have an ETA (or dependencies) for merging docs back into master?
Cheers,
Dirkjan
Re: couch has docs!
Posted by "Michael Zedeler." <mi...@zedeler.dk>.
Hi Dave, Dirkjan, Alexander, Jan and Noah.
Great job! Thanks!
Regards,
Michael.
On 2012-09-26 23:02, Dave Cottlehuber wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
Re: couch has docs!
Posted by Noah Slater <ns...@tumbolia.org>.
Okay, I've been at this all day.
I've moved a lot of stuff around, and the whole thing is in flux. But
basically, I've integrated the docs to the point where `make distcheck`
works. And while I have started to align things, nothing else actually
happens. They are not built or installed.
I'll get to that next.
On Wed, Sep 26, 2012 at 10:02 PM, Dave Cottlehuber <dc...@jsonified.com>wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]:
> https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
>
--
NS
Re: couch has docs!
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Wed, Sep 26, 2012 at 11:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
> - /docs/ lags master a wee bit, nothing serious
Do we have an ETA (or dependencies) for merging docs back into master?
Cheers,
Dirkjan
Re: couch has docs!
Posted by Octavian Damiean <ma...@gmail.com>.
Great stuff. Thanks to all involved!
I'll make sure to read through it and I'll be more than happy to help you
out with the Wiki cleanup/transferal.
Cheers,
Octavian Damiean
On Wed, Sep 26, 2012 at 11:02 PM, Dave Cottlehuber <dc...@jsonified.com>wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]:
> https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
>
Re: couch has docs!
Posted by Octavian Damiean <ma...@gmail.com>.
Great stuff. Thanks to all involved!
I'll make sure to read through it and I'll be more than happy to help you
out with the Wiki cleanup/transferal.
Cheers,
Octavian Damiean
On Wed, Sep 26, 2012 at 11:02 PM, Dave Cottlehuber <dc...@jsonified.com>wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]:
> https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
>
Re: couch has docs!
Posted by Benoit Chesneau <bc...@gmail.com>.
nice works. Thanks all!
On Wed, Sep 26, 2012 at 11:02 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
> Hi,
>
> After much hand-wringing & gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan & Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes & fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long & Document!
>
> Notes & Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
Re: couch has docs!
Posted by "john.tiger" <jo...@gmail.com>.
On 09/26/2012 03:47 PM, Dave Cottlehuber wrote:
> On 26 September 2012 23:44, john.tiger<jo...@gmail.com> wrote:
>> okay, thks - now what is plan - if docs go into /couchdb/docs then should
>> stuff in wiki be ported over ? having both docs and wiki is confusing
>> unless really clear what goes into what.
> My evil plan is to review each wiki page 1 by 1, remove cruft, and
hardly evil - more like lots of hard much appreciated work
we'll start reviewing the docs and add where we have any better info
meanwhile, any ideas on changing the main web page - adding stubs for
some of the docs and community menu items ?
> transfer the rest into rst format. Common sense should indicate what
> changes a lot& what's reliable.
>
> A+
> Dave
>
Re: couch has docs!
Posted by Dave Cottlehuber <dc...@jsonified.com>.
On 26 September 2012 23:44, john.tiger <jo...@gmail.com> wrote:
> okay, thks - now what is plan - if docs go into /couchdb/docs then should
> stuff in wiki be ported over ? having both docs and wiki is confusing
> unless really clear what goes into what.
My evil plan is to review each wiki page 1 by 1, remove cruft, and
transfer the rest into rst format. Common sense should indicate what
changes a lot & what's reliable.
A+
Dave
Re: couch has docs!
Posted by "john.tiger" <jo...@gmail.com>.
okay, thks - now what is plan - if docs go into /couchdb/docs then
should stuff in wiki be ported over ? having both docs and wiki is
confusing unless really clear what goes into what.
On 09/26/2012 03:02 PM, Dave Cottlehuber wrote:
> Hi,
>
> After much hand-wringing& gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan& Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes& fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long& Document!
>
> Notes& Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
>
Re: couch has docs!
Posted by Dave Cottlehuber <dc...@jsonified.com>.
On 27 September 2012 21:34, Eli Stevens (Gmail) <wi...@gmail.com> wrote:
> On Thu, Sep 27, 2012 at 1:02 PM, john.tiger <jo...@gmail.com> wrote:
>> look, if it was a simple markdown text file download, I'd already be reading
Hi John,
We really want this to be easy, easy as py. Hem.
Send me something in markdown and I'll restify it for you. Or you can
use pandoc[1] either as a web service (paste in md, get out rst) or
locally installed.
You can use the github editor online [2] to edit your fork in rst
format and flick back between preview mode. You don't need anything
locally installed at all in this case.
Both of these options are documented on the wiki[2] and mentioned both
times in my last 2 emails.
A+
Dave
[1]: http://johnmacfarlane.net/pandoc/try
[2]: http://wiki.apache.org/couchdb/Documentation#Driving_GitHub_UI
Re: couch has docs!
Posted by "Eli Stevens (Gmail)" <wi...@gmail.com>.
On Thu, Sep 27, 2012 at 1:02 PM, john.tiger <jo...@gmail.com> wrote:
> look, if it was a simple markdown text file download, I'd already be reading
I don't think that a project with the scope of CouchDB is ever going
to be well served by "simple" documentation.
> and making updates instead of f.. ing around trying to install a bunch of
> scripts - I already wasted a couple of hours last night just trying to get
> this stuff - want contibutors, make it simple. screwed around with rst a
> few years ago - waste of time.
Maybe instead you could explain what issues you're encountering, so
that someone can help get them fixed for you, and documented for the
next person who runs into them?
Eli
Re: couch has docs!
Posted by "john.tiger" <jo...@gmail.com>.
On 09/27/2012 01:28 PM, Benoit Chesneau wrote:
> On Thu, Sep 27, 2012 at 9:07 PM, john.tiger<jo...@gmail.com> wrote:
>> On 09/27/2012 12:39 AM, Dave Cottlehuber wrote:
>>> On 27 September 2012 07:07, john.tiger<jo...@gmail.com> wrote:
>>>> maybe it's late, but I cannot figure out the docs build from linux
>>>> "make html" did not work, neither did python conf.py - what am i missing
>>>> ?
>>> Hi John,
>>>
>>> Thanks for giving it a go. I've not tested the python stuff on linux
>>> so it might be some platform specific issue I'm missing.
>>>
>>> 0. You'll need to `git checkout -b origin/docs` to switch to the only
>>> branch that has the doc stuff in it
>>> 1.
>>> http://wiki.apache.org/couchdb/Documentation#Setting_up_Python_and_Sphinx_for_the_first_time
>>> 2. run this which should work:
>>>
>>> sphinx-build -a -E -W -n \
>>> -D version='$ver' \
>>> -D release='$ver-git-sha' \
>>> -D project='Apache CouchDB' \
>>> -D copyright='$year, Apache Software Foundation' \
>>> -d $TMPDIR/couchdocs/ \
>>> rst/ \
>>> `pwd`/manual
>>>
>>> Feel free to give the github approach a go
>>>
>>> http://wiki.apache.org/couchdb/Documentation#Editing_Documentation_via_GitHub
>>> as well.
>>
>> ugh, pythoners always make things more complex and time wasting - markdown
>> is so much simpler, no compiling necessary and more compatible with github
>>
> sure so you run markdown.py and here we go. Oh damn it's python. does
> it means markdown is also complex?
>
look, if it was a simple markdown text file download, I'd already be
reading and making updates instead of f.. ing around trying to install a
bunch of scripts - I already wasted a couple of hours last night just
trying to get this stuff - want contibutors, make it simple. screwed
around with rst a few years ago - waste of time.
Re: couch has docs!
Posted by Benoit Chesneau <bc...@gmail.com>.
On Thu, Sep 27, 2012 at 9:07 PM, john.tiger <jo...@gmail.com> wrote:
> On 09/27/2012 12:39 AM, Dave Cottlehuber wrote:
>>
>> On 27 September 2012 07:07, john.tiger<jo...@gmail.com> wrote:
>>>
>>> maybe it's late, but I cannot figure out the docs build from linux
>>> "make html" did not work, neither did python conf.py - what am i missing
>>> ?
>>
>> Hi John,
>>
>> Thanks for giving it a go. I've not tested the python stuff on linux
>> so it might be some platform specific issue I'm missing.
>>
>> 0. You'll need to `git checkout -b origin/docs` to switch to the only
>> branch that has the doc stuff in it
>> 1.
>> http://wiki.apache.org/couchdb/Documentation#Setting_up_Python_and_Sphinx_for_the_first_time
>> 2. run this which should work:
>>
>> sphinx-build -a -E -W -n \
>> -D version='$ver' \
>> -D release='$ver-git-sha' \
>> -D project='Apache CouchDB' \
>> -D copyright='$year, Apache Software Foundation' \
>> -d $TMPDIR/couchdocs/ \
>> rst/ \
>> `pwd`/manual
>>
>> Feel free to give the github approach a go
>>
>> http://wiki.apache.org/couchdb/Documentation#Editing_Documentation_via_GitHub
>> as well.
>
>
> ugh, pythoners always make things more complex and time wasting - markdown
> is so much simpler, no compiling necessary and more compatible with github
>
sure so you run markdown.py and here we go. Oh damn it's python. does
it means markdown is also complex?
Re: couch has docs!
Posted by "john.tiger" <jo...@gmail.com>.
On 09/27/2012 12:39 AM, Dave Cottlehuber wrote:
> On 27 September 2012 07:07, john.tiger<jo...@gmail.com> wrote:
>> maybe it's late, but I cannot figure out the docs build from linux
>> "make html" did not work, neither did python conf.py - what am i missing ?
> Hi John,
>
> Thanks for giving it a go. I've not tested the python stuff on linux
> so it might be some platform specific issue I'm missing.
>
> 0. You'll need to `git checkout -b origin/docs` to switch to the only
> branch that has the doc stuff in it
> 1. http://wiki.apache.org/couchdb/Documentation#Setting_up_Python_and_Sphinx_for_the_first_time
> 2. run this which should work:
>
> sphinx-build -a -E -W -n \
> -D version='$ver' \
> -D release='$ver-git-sha' \
> -D project='Apache CouchDB' \
> -D copyright='$year, Apache Software Foundation' \
> -d $TMPDIR/couchdocs/ \
> rst/ \
> `pwd`/manual
>
> Feel free to give the github approach a go
> http://wiki.apache.org/couchdb/Documentation#Editing_Documentation_via_GitHub
> as well.
ugh, pythoners always make things more complex and time wasting -
markdown is so much simpler, no compiling necessary and more compatible
with github
>
> The wiki is ripe for updating if you get it to work; I'm away for the
> next few days.
>
> A+
> Dave
>
Re: couch has docs!
Posted by Dave Cottlehuber <dc...@jsonified.com>.
On 27 September 2012 07:07, john.tiger <jo...@gmail.com> wrote:
> maybe it's late, but I cannot figure out the docs build from linux
> "make html" did not work, neither did python conf.py - what am i missing ?
Hi John,
Thanks for giving it a go. I've not tested the python stuff on linux
so it might be some platform specific issue I'm missing.
0. You'll need to `git checkout -b origin/docs` to switch to the only
branch that has the doc stuff in it
1. http://wiki.apache.org/couchdb/Documentation#Setting_up_Python_and_Sphinx_for_the_first_time
2. run this which should work:
sphinx-build -a -E -W -n \
-D version='$ver' \
-D release='$ver-git-sha' \
-D project='Apache CouchDB' \
-D copyright='$year, Apache Software Foundation' \
-d $TMPDIR/couchdocs/ \
rst/ \
`pwd`/manual
Feel free to give the github approach a go
http://wiki.apache.org/couchdb/Documentation#Editing_Documentation_via_GitHub
as well.
The wiki is ripe for updating if you get it to work; I'm away for the
next few days.
A+
Dave
Re: couch has docs!
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Thu, Sep 27, 2012 at 7:07 AM, john.tiger <jo...@gmail.com> wrote:
> maybe it's late, but I cannot figure out the docs build from linux
> "make html" did not work, neither did python conf.py - what am i missing ?
It would be helpful if you were somewhat more specific than "did not work".
In any case, you need to install the Sphinx tool (written in Python),
along with its dependencies (just docutils and pygments, I think).
easy_install, pip, or your friendly local package manager should be
able to handle this with ease.
Cheers,
Dirkjan
Re: couch has docs!
Posted by "john.tiger" <jo...@gmail.com>.
maybe it's late, but I cannot figure out the docs build from linux
"make html" did not work, neither did python conf.py - what am i missing ?
On 09/26/2012 03:02 PM, Dave Cottlehuber wrote:
> Hi,
>
> After much hand-wringing& gnashing of teeth, we now have a /docs/
> branch in git[1], [2], and available online [3]. A huge thank-you to
> Dirkjan Ochtman, Alexander Shorin, and the tireless Jan& Noah to make
> this happen. The single biggest thing you can do as thanks, is to send
> us improvements, in any form you feel comfortable, and in any size.
>
> Sending in changes& fixes should be as easy as 1-2-3:
>
> 1: fork locally with git, or github
> 2: edit the .rst format [7] files either in the slick github UI, or in
> your favourite editor
> 3: send a pull request, mail, jira, or a patch as you prefer
>
> I hopefully documented those steps [4] so please let me know if it
> works. Live Long& Document!
>
> Notes& Tips:
> - /docs/ lags master a wee bit, nothing serious
> - feel free to use COUCHDB-1536 for tracking any integration work in
> the /docs/ branch
> - you can use pandoc online [5] to convert from your favourite format
> - it looks like github lets you edit in markdown but send in changes
> in rst format
>
> [1]: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs
> [2]: https://github.com/apache/couchdb/tree/docs
> [3]: http://couchdb.readthedocs.org/en/latest/index.html
> [4]: http://wiki.apache.org/couchdb/Documentation
> [5]: http://johnmacfarlane.net/pandoc/try
> [6]: https://issues.apache.org/jira/browse/COUCHDB-1536
> [7]: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
>
> A+
> Dave
>