pydoctor: Recommended markup language
![](https://secure.gravatar.com/avatar/148a51ecc80531586e1f5530d64b988a.jpg?s=120&d=mm&r=g)
Hello togehter, I am not sure this is the right place for pydoctor related discussions. The topic are pydoctor's different supported markup languages [1]. The question seems simple and maybe you can put it to the FAQ [2] of pydoctor. Which of the markup languages would you recommend for a new pydoctor user? I assume that you use "epydoc" for Twisted, right? But I also assume that you use it because of historical reasons because pydoctor was born out of epydoc, right? I know a bit Google and numpy style from sphinx. I also know Doxygen "style". But I haven't used one of them long enough to make a decision. I would say a docu style should... - be readable in source code - fit to Python concepts - support markup (bold text, code blocks, ...) - less complex for newbies, in the meaning of not to many options/possibilities So what is your opinion in that? Kind Christian [1] -- <https://github.com/twisted/pydoctor#markup> [2] -- <https://pydoctor.readthedocs.io/en/latest/faq.html>
![](https://secure.gravatar.com/avatar/e1554622707bedd9202884900430b838.jpg?s=120&d=mm&r=g)
I think it’s a bit of a toss-up. Why Epydoc? A lot of intended-for-pydoctor documentation (i.e.: lots and lots of Twisted) is written in this format, so it is easy to find examples for what you might want to do specifically in the context of API docs. Syntax for the things that you want to do frequently in API documentation are clear and unambiguous. The way PyDoctor uses certain ReST markup is subtly different from the way that Sphinx uses it; for example, `` is an API reference in a docstring context, as opposed to a generalized documentation index reference; Epydoc will be handled consistently. It’s a little simpler. Errors will show up in the correct location (https://github.com/twisted/pydoctor/issues/237 <https://github.com/twisted/pydoctor/issues/237> - although eventually, one should hope, that bug will be fixed) It’s the better-tested code path since it’s been around for a decade and huge codebases are using it. Why ReST? Although its integration with Pydoctor is newer, its parser is much better maintained. Far more formatting features - although (see “it’s simpler”) this might not always be what you want. It’s probably the same format you’re using for your narrative documentation. You won’t need to teach contributors with other open source experience how to use it. Ultimately, which one is appropriate depends on your priorities, but also, I would encourage you not to waste too much time on this ultimately superficial decision. Either choice is totally fine, and will not make or break your project.
![](https://secure.gravatar.com/avatar/e1554622707bedd9202884900430b838.jpg?s=120&d=mm&r=g)
I think it’s a bit of a toss-up. Why Epydoc? A lot of intended-for-pydoctor documentation (i.e.: lots and lots of Twisted) is written in this format, so it is easy to find examples for what you might want to do specifically in the context of API docs. Syntax for the things that you want to do frequently in API documentation are clear and unambiguous. The way PyDoctor uses certain ReST markup is subtly different from the way that Sphinx uses it; for example, `` is an API reference in a docstring context, as opposed to a generalized documentation index reference; Epydoc will be handled consistently. It’s a little simpler. Errors will show up in the correct location (https://github.com/twisted/pydoctor/issues/237 <https://github.com/twisted/pydoctor/issues/237> - although eventually, one should hope, that bug will be fixed) It’s the better-tested code path since it’s been around for a decade and huge codebases are using it. Why ReST? Although its integration with Pydoctor is newer, its parser is much better maintained. Far more formatting features - although (see “it’s simpler”) this might not always be what you want. It’s probably the same format you’re using for your narrative documentation. You won’t need to teach contributors with other open source experience how to use it. Ultimately, which one is appropriate depends on your priorities, but also, I would encourage you not to waste too much time on this ultimately superficial decision. Either choice is totally fine, and will not make or break your project.
participants (2)
-
c.buhtz@posteo.jp
-
Glyph