Last but not the least, MMa's come with documentation bundles - for a good reason. And Sage's doc website relies on docs built by sphinx, and neglecting them already produced a mess there, which needs to be fixed, obviously not by hand.
On Tue, 29 Jan 2019 18:28 Dima Pasechnik <dimp...@gmail.com wrote: > On Tue, Jan 29, 2019 at 6:11 PM Nils Bruin <nbr...@sfu.ca> wrote: > > > > 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 "?...". 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. > > I find it hugely disruptive for the workflow to have to search for > things online. > > Also, the effort to create docs is already done, usually, it's just > the matter to tweak sphinx to have them built and installed. > > > > > 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. > > Given how much crap nowadays google returns for seemingly meaningful > searches, this is quite a waste of time to do. > > And you often get wrong versions of what you look for... > > > > > > -- > > 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. > -- 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.
