On Tuesday, February 16, 2021 at 10:45:30 AM UTC-8 vdelecroix wrote: > However, this externalizations comes with some inconvenience and > I would like to discuss one issue with documentation that was > raised in ticket #31404. Namely, the problem is that we want > something like `:mod:cypari2.gen` inside sage documentation to be > resolved by sphinx to what it should be (that could be: a link > to the documentation in SAGE_SHARE, to the local system > documentation on the computer or to online documentation).
My suggestion would be to focus on linking to online versions of package documentation first. Ticket https://trac.sagemath.org/ticket/27495 already describes a proposed design for this - comments and help with the implementation are welcome. Providing links to an offline copy of package documentation is secondary, in my opinion. But nevertheless, here are some thoughts: Splitting out the documentation of pplpy (as an example) into a separate package pplpy-doc could be a good design for various reasons: 1) pplpy-doc could be distributed as an architecture-independent wheel. 2) Building pplpy would not need Sphinx as a build system requirement (note that in modern Python packaging following PEP517/518, there is no such thing as an "optional build system requirement"). 3) Clear separation between the front-end environment and the kernel environment, as explained in https://trac.sagemath.org/ticket/30306 - pplpy-doc would be installed in the front-end environment (where the Jupyter notebook runs) and will not be needed in the kernel environment; whereas pplpy would not be needed in the front-end environment. 4) Using "extra-requires", installing pplpy with offline documentation could just be "pip install pplpy[doc]" (which would add the dependency on pplpy-doc) For a proposal for packaging of the documentation of Sage itself - please see https://trac.sagemath.org/ticket/29868 (pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf) - comments and help with the implementation are welcome here too. Matthias -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/dc6ab03f-2ef2-4ba1-9929-a8061e30dcf6n%40googlegroups.com.
