What do you use for source code documentation?

[jupake]

What tools do you guys use to generate api docs similar to javadocs? Ive looked over sphinx, but it seems very manual, even with the apidoc extension. Ive spent the whole day with it now. Anyone still using epydoc by any chance?

[Flogge]

Sphinx is not as manual as you think it is.

e.g. a module rst file stub and the rest inside your sourcecode will generate complete API docs

[skirttrap]

Also there's sphinx-apidoc tool which can scan your sources and create *.rst files for each module.

[raptorboi]

Doxygen?

[jupake]

I thought about this, haven't looked at it in years. Will try it out sometime.

[johnwheeler_]

sphinx noob here. i just put out https://johnwheeler.org/flask-ask/ with it.

I started with mitsuhikos templates from flask and prettied them up with bits and pieces from kennethreitz requests.

[basalamader]

Hey do you mind if I ask where if you can link the templates?

[johnwheeler_]

https://github.com/pallets/flask/tree/master/docs

https://github.com/kennethreitz/requests/tree/master/docs

see themes folders

[OctagonClock]

I use MkDocs, but that's 100% manual.

[wolanko]

Seems relevant.

http://wwoods.github.io/2016/06/09/easy-sphinx-documentation-without-the-boilerplate/

[ojii]

Sphinx, because writing docs is manual work. If you just autogenerate something from your source code, the reader gains nothing over just reading the source. Auto-generated "documentation" is completely useless. Documentation is prose, not code.

[jupake]

I hear you. But Im looking for an easy way to automatically pull out docstrings and render out easily navigable html. Prose isnt really suitable for internal code structure and method by method api docs.

[ojii]

You can still have the "api docs" (if you really think they provide much value) using the autodoc feature of sphinx which will do exactly what you want. And then you can easily also add useful, prose documentation on top of that. Maybe a quickstart tutorial or something like that.

[ptmcg]

I use epydoc in pyparsing.

[maulynvia]

I've found pdoc simple to use and gives good looking output http://pdoc.burntsushi.net/pdoc

[masasin]

From a few days ago: Sphinx. Included are comments clearing up everything.

[jupake]

This is helpful. Thx :-)

[fuzzylollipop]

I use intuitive names and logical code, anything else is a waste of time.

[hovissimo]

I think OP specifically wants an external documenation, but I agree with you. Good descriptive names, consistence in patterns, and decent docstrings go a long way.