Le 29/01/2019 à 19:10, Nils Bruin a écrit :
On Tuesday, January 29, 2019 at 12:34:39 AM UTC-8, vdelecroix wrote:Dear all, Imagine I have a Python module, typically hosted on PyPI and depending on SageMath, that provides documentation in some form (e.g. a pdf file, a sphinx repo, etc). 1) When a user performs `sage -pip install X`, should the documentation be compiled and installed? If the answer is yes (I believe it is)From a usability point of view: I think the docstring documentation is certainly expected to be there, because it gets accessed via "?...".
These are the docstrings. But it leaves aside any possible additional documentation that is not part of the sources. It can be tutorial, a detailed computation example, a tour overview, etc We have many of those inside Sage. And I don't see any reason, as Sage is becoming more modular, to have more of them in the packages as well.
I don't think that needs any extra action, though. I think many people would expect other documentation to be available online nowadays. I certainly access python's documentation online exclusively. If docs come in PDF form, I'd probably download it. It's definitely nice to have docs available off-line as well, but I think relatively few people will find it or know it exists if it gets installed automatically somewhere in the filesystem. Therefore, my hunch is that putting effort into it will have relatively low return. The advantage of using "google" or "duckduckgo" to find the relevant documentation is that it's a strategy that's independent of the software for which you're looking for the documentation.
One of the many advantage of "inside Sage" installation that I already mentioned is that you have "live documentation". That is executable and modifiable examples in a Jupyter interface. Vincent -- 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 post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
