Notice: In order to edit this ticket you need to be either: a Product Owner, The owner or the reporter of the ticket, or, in case of a Task not yet assigned, a team_member"

Task #9371 (closed)

Opened 8 years ago

Closed 5 years ago

Last modified 5 years ago

Move from epydoc to sphinx

Reported by: jamoore Owned by: rleigh
Priority: critical Milestone: 5.x
Component: Documentation Version: 4.4.8
Keywords: n.a. Cc: sbesson, bpindelski, cblackburn, rleigh, python-team@…
Resources: n.a. Referenced By: n.a.
References: n.a. Remaining Time: n.a.
Sprint: n.a.

Description

Currently, the release-docs ant target invokes epydoc to generate a Python documentation download. If we plan on moving any of our plone/trac documentation to sphinx (and perhaps even if not) it would make sense to remove the epydoc dependency in favor of sphinx. Things that will need to be looked into:

  • Changing the top-level build to invoke sphinx
  • Possibly adding a requirements.txt file for easily installing sphinx
  • Changing any epydoc formatting to sphinx formatting where it would cause immediate build errors or confusion
  • Integrating the generated API documents into the output of docs/sphinx (or vice versa integrating the output of docs/sphinx with the rest of the top-level build)

Things that are likely out-of-scope for this task, and should be handled later or via another story:

  • Modifying all files to have proper sphinx document blocks
  • ...

See also #9345 for other commits that affect the build (like OMERO.docs.zip)

Change History (17)

comment:1 Changed 8 years ago by bpindelski

  • Cc bpindelski added; blazej removed

comment:2 Changed 8 years ago by rleigh

  • Owner set to rleigh
  • Status changed from new to accepted

comment:3 Changed 8 years ago by rleigh

I've added initial support for generating the API reference using sphinx-apidoc here:

https://github.com/rleigh-dundee/openmicroscopy/commits/sphinx

Docs are in docs/sphinx-api. The Makefile contains an "api" target to generate the rst files for the document hierarchy. The standard "html" target will then autogenerate the reference from this structure.

Only error in the source code during parsing is:

Traceback (most recent call last):ero.util                                      
  File "/usr/lib/pymodules/python2.7/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
  File "/home/rleigh/code/ome/dist/lib/python/omero/util/ROI_utils.py", line 45, in <module>
    from omero.model import TextI
ImportError: cannot import name TextI

There are, of course, hundreds of warnings while generating the docs due to the markup being incorrect or absent, which will need to be fixed up.

If we create a top-level sphinx directory (maybe move the existing manual to sphinx-user?), we can then reference all the sub-manuals when generating a complete manual. Or we could just keep them separate.

Roger

comment:4 Changed 8 years ago by jmoore

TextI is just a bug. Feel free to fix it on your branch.

As for the rest, not sure of the best way forward. Probably need to take a look at it next week and see whether or not to prioritize it.

comment:5 Changed 8 years ago by jmoore

  • Milestone changed from OMERO-4.4.4 to OMERO-4.5

This won't be happening for 4.4.4. Pushing.

comment:6 Changed 8 years ago by jmoore

Referencing ticket #6382 has changed sprint.

comment:7 Changed 8 years ago by hflynn

Isn't this resolved now? Or is there remaining work to be done to complete the move to Sphinx?

comment:8 Changed 8 years ago by jmoore

No sorry. epydoc is the generated API documentation for all the Python code. That hasn't been converted (fully) yet.

comment:9 Changed 8 years ago by rleigh

Enabling the generation of Sphinx API docs is just a few lines of changes. However, it doesn't really make sense to do this without also converting the epydoc source comments into the sphinx equivalant (and perhaps fixing and completing the documentation at the same time). However, this part really needs doing by people who are intimate with the APIs in question. I can certainly put the small changes to enable this onto a public branch if it's not already there.

comment:10 Changed 7 years ago by jburel

  • Version set to 4.4.8

Roger: is this in the pipeline for the summer effort: Testing and Docs?

comment:11 Changed 7 years ago by rleigh

https://github.com/rleigh-dundee/openmicroscopy/tree/sphinx-epydoc contains my work on this to date. I've not done any further work on this myself; it really needs tackling by people familiar with the code, since the bulk of the work here is the API documentation.

comment:12 Changed 7 years ago by hflynn

Who is the best person to assign this ticket to then? Does anyone have time to tackle it this month?

comment:13 Changed 7 years ago by rleigh

Probably someone intimately familar with the python code. Will or Ola maybe? The "making it work with sphinx" part is totally trivial as above, but replacing all the epydoc markup with sphinx markup unfortunately requires understanding of the code to document it properly.

comment:14 Changed 7 years ago by jamoore

  • Cc cblackburn python-team@… added; wmoore cneves removed

Anyone on python-team would be able to look into it. Having a readme with the instructions on how we do (code) documentation would also be useful, similar to how we got everyone ramped up on sphinx.

comment:15 Changed 5 years ago by sbesson

  • Resolution set to fixed
  • Status changed from accepted to closed

comment:16 Changed 5 years ago by rleigh

Was the markup in the source code fully converted to Sphinx? While I haven't kept a close eye on this, I thought this was still to be started.

comment:17 Changed 5 years ago by sbesson

Agreed. This is a post-migration task we still need to go over as mentioned in the last paragraph of the ticket description. I created a follow-up card (https://trello.com/c/IbBJVwLf/633-omero-py-sphinx-api-cleanup) and we can discuss its milestone next time we review the DevX board.

Note: See TracTickets for help on using tickets. You may also have a look at Agilo extensions to the ticket.

1.3.13-PRO © 2008-2011 Agilo Software all rights reserved (this page was served in: 0.76536 sec.)

We're Hiring!