#readthedocs

Morning folks

sup

good morning!

hi there

ericholscher: would it be possible to update MPL on RTD to >=1.4? There were some bugs with the plot directive that have been fixed in that version, and 1.4 has now been out for a bit

ericholscher: hi! when editing the list of branches for Twisted, rtd gets suuuuuuper slow

ericholscher: the branches that RTD builds, that is

i'm guessing that's maybe expected?

ericholscher: would it also be possible to update setuptools to the latest version? I have some dependencies in my pip requirements file that are failing with the error: The required version of setuptools (>=14.3.1) is not available

hawkowl: aye, i'm guessing you have a ton -- we should probably figure out a way to prune them

astrofrog1: aye, we should update *all the versions*:)

ericholscher: yeah we have a lot of branches on our github even

ericholscher: we prune from svn but pruning from github is more interesting

ericholscher: in the meantime i figured out that editing the url is a bit quicker

(editing /version/<version>/ to point to the new one i want)

does rtd have an api? *checks*

not a good one

it's on the list

right

a use case for me is automatically adding the branch to the tag + setting it as the default for going to twisted.rtfd.org as part of the release process scripting

yea, in theory we should be doing that automagically as your stable release, but i'm guessing our parsing is not handling your tag names properly

ericholscher: also the top of this webpage is super broke http://read-the-docs.readthedocs.org/en/latest/...

ericholscher: our tag names are like twisted-15.1.0

yea, we should be smarter at parsing the name out

another thing to add to the long list

hehe

also i like the +/- thing in the rtd theme

that's a good feature

yea, we just shipped that w/ our 1.3 support :)

:)

i liek

we have a couple more big things coming soon as well that I'm excited about

hawkowl: another fun thing is the :caption: on toc trees in 1.3 -- which let you get the fancy menu headers that we have on our docs

ooooooooh

Yeah, it totally threw me this morning attempting to get THAT to work with an older version of RTD

"What do you MEAN caption isn't a real tag?!"

Turns out.... :/

well on the Twisted side of docs, next pydoctor version won't look like it's from the 90s! https://dl.dropboxusercontent.com/u/14290114/py...

hawkowl: ooh -- I wanted to ask about pydoctor

i still need to figure out what non-twisted people do about api docs

can it output to json or some intermediary format other than HTML for pulling docstrings?

and does it parse instead of import the code?

ericholscher: it does something with sphinx inventories

hawkowl: well, we actually are close to releasing a new sphinx api gen tool that uses epydoc -- but it seems old and unmaintained, but we wanted to parse stuff instead of import it

https://github.com/averagehuman/python-epyparse is what I used

ericholscher: pydoctor doesnt import it

pydoctor is static

i'd love to use pydoctor if that is a better way forward

which means that some things don't work well (eg. if you have fooFunction.__doc__ = """w/e""")

and I can easily get an in-memory representation from a set of files

but that's an edge case

agreed

ericholscher: you should be able to get it in some format

lemme check, i was reading through it

does pydoctor support py3 also?

ericholscher: sorry but i just snorted my drink a little

:D

heh

ericholscher: no, it doesn't

ericholscher: both because it's not under direct development and it has twisted deps that arent ported yet

up until last version it still used divmod

ah, none of these python parsers seem to be actively developed

I guess for most use cases just importing the code is easier

but its a *huge* hassle for RTD

ericholscher: essentially it's not actively developed because it works

if we could just generate API's from parsed python, the whole virtualenv/autodoc craziness would disappear, and that would be really big for us

ericholscher: there's bugs, and it's not the best, but hey

heh yea

that's what I found w/ epydoc as well

practicality is the enemy of perfect

ericholscher: but, pydoctor doesnt write directly to html

ericholscher: but it's kind of intertwined with twisted.web.template

because it does some rendering *to* html (optionally)

and then puts it *in* html

but you can access one layer below

interesting

ericholscher: okay so there's pydoctor.astbuilder

which turns an ast into pydoctor.model.Documentable instances

for example, a documentable will have a kind

which might be "Package" or s

so

sure

or a class

then you have like, thing.docstring to get the docstring

yup, seems like a nice abstraction

thanks for the info -- I'll look into it a bit more

!m hawkowl

You're doing good work, hawkowl!

ericholscher: but a lot of things will probably be in epydoc2stan

so formatting the actual epydoc into useful stuff is not... abstracted as much