PEP8 & Sphinx

[Lee Olayvar]

I'd like to start putting help into Tortuga but given its early state, where your vision is basically 100% of the drive, its hard for me to actually put up code. So with that said, i was wondering if you would like some help in making things compliant in PEP8 and Sphinx. Perhaps someone to just run around and standardize, prep for documentation, etc. I wont be able to actually "document" anything yet, simply because i dont know Tortuga well enough, but in the future i'd also be more than happy to do that.

If your interested in help from this side of the project, let me know. I'm keeping this public also, so we can discuss the actual standards in PEP8, Sphinx, and Your Own (you mentioned you have "a few of your own"), so were all on the same page. I'd also document that somewhere aswell.

---
Lee Olayvar

[Lee Olayvar]

heh, the person i am referring to is of course Ian Charnas.. to clear any confusion (if read 5 years from now ;).

---
Lee Olayvar

[Ian Charnas]

Lee, that's an excellent idea. I'm taking a short vacation, and when
I come back I will write up a coding standards document. It will not
be more than one page, and it will be easy to follow, I promise!
Another good way to get involved right away is to take a look at Babel
(or another system) and figure out how we can internationalize the
error messages. I want to be thinking about that from day one!

thank you!
ian

[Lee Olayvar]

On Sun, Nov 16, 2008 at 7:49 PM, Ian Charnas <ian.c...@gmail.com> wrote:

Lee, that's an excellent idea.  I'm taking a short vacation, and when
I come back I will write up a coding standards document.  It will not
be more than one page, and it will be easy to follow, I promise!
Another good way to get involved right away is to take a look at Babel
(or another system) and figure out how we can internationalize the
error messages.  I want to be thinking about that from day one!

How short of a vacation? (ie, 1 week, 2 weeks, etc.)

Just so i know not to bother checking the ML for a while heh ;)

--
Lee Olayvar

[Ian Charnas]

1 week.

[Lee Olayvar]

So hows it comin? Been rather dead the last week or so

--
Lee Olayvar

[Ian Charnas]

Lee, I hope I mentioned that I was going on vacation for a week.
Tomorrow I'll be back in work-mode, and I'll be looking at DVCS
systems and seeing if I can find a solution I can live with.

ian

[Sami Dalouche]

Looks like he doesn't want you to go on vacation ;-)

since you mentionned you loved google code, you could probably go with
bazaar, as it has some SVN export mechanism. Then, you have the best of
both worlds ;)

sami

[Lee Olayvar]

On Sat, Nov 29, 2008 at 12:31 PM, Ian Charnas <ian.c...@gmail.com> wrote:

Lee, I hope I mentioned that I was going on vacation for a week.
Tomorrow I'll be back in work-mode, and I'll be looking at DVCS
systems and seeing if I can find a solution I can live with.

Oh you did, two weeks ago, but i must have missed the start date of that haha. I thought you had been back for a week and haven't updated on Tortuga :).

Sounds good, i'd make more causes for my DVCS & Hosting choices but i believe that was well done in the other thread about this.

Thanks,
--
Lee Olayvar

[Lee Olayvar]

On the topic of Sphinx. What will Tortuga be using for API Docs? I've always heavily used/maintained API Docs with my projects via Epydocs. Now the idea behind that is simple, document the code as you write it (comments on functions, classes, vars, etc), and epydocs will take that and render it into pretty api documentation.

However sphinx confuses me some, what is its role in documentation for Tortuga? (Heck, im a bit confused on how any project uses sphinx, it almost sounds like its simply used to generate docs from separate rest files, entirely outside of the project code..)

Also, if Sphinx is not that great at making api docs, will we be using epydocs for the internal api documentation? (functions, etc?)

--
Lee Olayvar

[Mark Ramm]

TG2 uses sphinx to both autogenrate module docs from docstrings, and
to write rst files that compose the narrative docs for the project,
and I think it works pretty well.

--Mark Ramm

--
Mark Ramm-Christensen
email: mark at compoundthinking dot com
blog: www.compoundthinking.com/blog

[Ian Charnas]

Well, I had been maintaining my own documentation generator, called
EatTheSandwich. It used the epydoc parser and then generated
beautiful documentation from that. Sphinx has more features, although
it is a bit tedious to set up and the output is not a work of art, as
they say. I want to go ahead and use Sphinx, and I'll create
templates so that the output is prettier (and easier to read). Setup
will still be a pain, but I only have to do it once.

Epydocs isn't something I'm willing to consider, because it only scans
source code to do API documentation. Sphinx on the other hand, allows
you to generate an entire documentation website (with tutorials that
have embedded doctests, API documentation, tables of contents,
navigation, search capability, and so on). It also supports
templating, understands newer python syntax.. the list goes on.

I always heavily comment my code, and use docstrings just about
everywhere. Once the Tortuga API looks stable enough, I'll set up
Sphinx and go through the code to make those final touchups so Sphinx
can generate cross-references and so on.

ian

[Chris Perkins]

Ian,

I agree with you about the boilerplate stuff for spinx.  I wrote autosummary with help from a base version written by the numpy folks.  It will manage most of the boilerplate creation for your module, especially if you ahve good doc strings.  Here is a thread about it:
http://groups.google.com/group/sphinx-dev/browse_thread/thread/583cb5fa6d31352b/ed3b0935e9bc6705?lnk=gst&q=percious#ed3b0935e9bc6705
and here is the bit bucket branch:
http://www.bitbucket.org/percious/sphinx-autosummary/
if you need help getting going let me know.

cheers.
-chris

On Sun, Dec 14, 2008 at 3:57 PM, Ian Charnas <ian.c...@gmail.com> wrote:

Well, I had been maintaining my own documentation generator, called
EatTheSandwich.  It used the epydoc parser and then generated
beautiful documentation from that.  Sphinx has more features, although
it is a bit tedious to set up and the output is not a work of art, as
they say.  I want to go ahead and use Sphinx, and I'll create
templates so that the output is prettier (and easier to read).  Setup
will still be a pain, but I only have to do it once.

Epydocs isn't something I'm willing to consider, because it only scans
source code to do API documentation.  Sphinx on the other hand, allows
you to generate an entire documentation website (with tutorials that

have  doctests, API documentation, tables of contents,

[Ian Charnas]

Chris, thanks for sharing that. I'll look into it when the time comes. - ian

[Lee Olayvar]

Sounds good. My only concern was that we wouldn't have developer friendly API Documentation, something which i feel Epydocs does a great job at. Not to say ofcourse, that Sphinx doesn't, i just didnt know if it did or not.

As long as API Docs are being considered, i'll dive fully into Sphinx for my own projects aswell, so i can have a good grasp on it for the future. From what i've seen, Sphinx by itself is a major pain in the arse without autosummary, but talking with Chris last night left me with the impression that with autosummary will be able to handle automatic of basic api docs just fine.