Opened 13 months ago

Last modified 4 months ago

#30893 needs_work enhancement

Replace sage autodoc extension by built-in one

Reported by: gh-tobiasdiez Owned by:
Priority: major Milestone: sage-9.5
Component: documentation Keywords:
Cc: jhpalmieri, klee Merged in:
Authors: Tobias Diez Reviewers:
Report Upstream: N/A Work issues: Make docbuild pass
Branch: public/documentation/replaceautodoc (Commits, GitHub, GitLab) Commit: ca98b7a0dda77b3474dd4dae610574deef05e76b
Dependencies: #30884 Stopgaps:

Status badges

Description (last modified by gh-tobiasdiez)

Replaces sage's custom autodoc extension by the built-in one. The motivation is to add support for typing information in the documentation in #30894.

For some reason, my local installation only wants to build the documentation for the manifold package. For this, I verified that the newly generated documentation is on par with the old one. This was the case except for parameters added with the @output decorator. This should be fixed with #30884. Please let me know if there are other customization in the sage autodoc file except for the sage_wraps decorator support.

Change History (11)

comment:1 Changed 13 months ago by gh-tobiasdiez

  • Authors set to Tobias Diez
  • Cc mkoeppe added
  • Status changed from new to needs_review

comment:2 Changed 13 months ago by git

  • Commit changed from 222059565bc2166f29c50a6d85db7992589098c2 to f149da6fc5bb005aa4f70f9034af616e1bfde5b3

Branch pushed to git repo; I updated commit sha1. New commits:

f149da6Replace sage autodoc extension by built-in one

comment:3 Changed 13 months ago by gh-tobiasdiez

  • Description modified (diff)

comment:4 Changed 13 months ago by mkoeppe

  • Cc jhpalmieri added; mkoeppe removed

comment:5 Changed 13 months ago by jhpalmieri

  • Cc klee added

comment:6 follow-up: Changed 13 months ago by jhpalmieri

Building the docs fails immediately for me, because text roles like :arxiv:, :trac:, etc. are no longer defined.

I think it would be better, at least as a first step, to update sage_autodoc to incorporate the recent changes in Sphinx's autodoc.

comment:7 Changed 13 months ago by jhpalmieri

My understanding is that one of the main reasons for using our own version of autodoc is to be able to include Cython files in the documentation, and this requires customization of the introspection code. So that is something you should test when experimenting with this: how is autodoc working on Cython files?

comment:8 in reply to: ↑ 6 Changed 13 months ago by gh-tobiasdiez

  • Status changed from needs_review to needs_work
  • Work issues set to Make docbuild pass

Thanks for the input @jhpalmieri.

Building the docs fails immediately for me, because text roles like :arxiv:, :trac:, etc. are no longer defined.

That should be fixed now.

I think it would be better, at least as a first step, to update sage_autodoc to incorporate the recent changes in Sphinx's autodoc.

I tried rebasing first, but there were quite a few changes which made it rather difficult. So I thought replacing it completely, and then implement the necessary changes elsewhere would be easier.

should test when experimenting with this: how is autodoc working on Cython files?

I will do so! I just figured out how to convince sage to produce the documentation for something else then the manifold package. After playing around a bit, I realized that there might be quite some changes necessary (e.g. instancedoc doesn't play nicely with Python's inspect). Will keep you updated.

comment:9 Changed 13 months ago by git

  • Commit changed from f149da6fc5bb005aa4f70f9034af616e1bfde5b3 to ca98b7a0dda77b3474dd4dae610574deef05e76b

Branch pushed to git repo; I updated commit sha1. New commits:

ca98b7aFix extlinks

comment:10 Changed 10 months ago by mkoeppe

  • Milestone changed from sage-9.3 to sage-9.4

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

comment:11 Changed 4 months ago by mkoeppe

  • Milestone changed from sage-9.4 to sage-9.5

Setting a new milestone for this ticket based on a cursory review.

Note: See TracTickets for help on using tickets.