Add library reference section

Issue #1 new
Thijs Triemstra
created an issue

Hi Kevin, what do you think about moving to sphinx's API capabilities vs. the current pydoctor/epydoc situation? This would make linking to classes in the documentation much easier. I don't think this is covered in your documentation so I thought I'd open a ticket. I'd be happy to help out, feel free to add me as a maintainer/committer and assign tickets to me, cheers.

Comments (1)

  1. Kevin Horn repo owner

    While I think it would be good idea to transition the Twisted API docs over to Sphinx (away from pydoctor/Epydoc), I think that's outside the scope of the current project. Here's why...

    • It would be decidedly non-trivial. Some kind of tool would probably need to be created to translate the current Epydoc markup in docstrings into rest/Sphinx markup...and that markup is used in docstrings throughout Twisted. That's a lot of files.
    • Sphinx can't (yet) do everything that pydoctor can (good support for interfaces, for example)
    • I'm not sure how the rest of the Twisted community would feel about this. Maybe they'd like it fine, but I bet they'd need some convincing, and I'd rather focus on getting the long-form docs transistioned over first.

    In short, let's leave this until after the main Sphinx transition has occurred.

    All that said, It can't hurt to leave this open in case anyone wants to discuss it further here...

  2. Log in to comment