Task #9371 (closed)
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 12 years ago by bpindelski
- Cc bpindelski added; blazej removed
comment:2 Changed 12 years ago by rleigh
- Owner set to rleigh
- Status changed from new to accepted
comment:3 Changed 12 years ago by rleigh
comment:4 Changed 12 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 12 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 12 years ago by jmoore
Referencing ticket #6382 has changed sprint.
comment:7 Changed 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 8 years ago by sbesson
- Resolution set to fixed
- Status changed from accepted to closed
Done as part of https://github.com/openmicroscopy/openmicroscopy/pull/2599 and follow-up PRs.
comment:16 Changed 8 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 8 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.
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:
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