improve accessibility of the documentation

[mantepse]

I'm not sure (especially because Sage-mode is already very good), but it may make sense to make the html documentation (in a browser) easily accessible.

Right now, I noticed two reasons why I'd like to do this:

1) an overview of a module:

To get an overview of a module, reading the module's docstring via, for example, sage.combinat.posets? is not always helpful, because sphinx cross-references are not resolved. This would actually be better dealt with in Sage-mode itself, but I have no idea how.

2) pictures

(not so important for me currently)

[stakemori]

Thank you very much for your advice. You mean an Emacs command for browse_sage_doc(object)? I will add such a command this week end.

[mantepse]

I just noticed that sphinx can produce texinfo. Is this what is used in emacs?

[stakemori]

I'm not sure. The output in *Sage Document* buffer of an object is exactly same as the output of object? in Sage inside a terminal.

[mantepse]

I posted a question here: https://groups.google.com/forum/#!topic/sage-devel/MjhzbpqnLXs

could you use texinfo documentation?

[mantepse]

I can now produce a complete (hyperlinked, with pictures!) manual in the info format. Manually, you were already able to do this, by calling make in each subdirectory of the texinfo tree, so there is not much difference to what you already know. (unfortunately info links only work correctly starting with emacs 25...)

So, is it possible to visit an info node by typing "object?"? Moreover, would it be possible to enable Sage-doc mode as a minor mode when looking at this documentation, or is there a better solution? (I still want to be able to execute examples with "C-c C-d")

Many thanks for all your work!

[stakemori]

Thank you for your hard work. I just built info files using your patch.

Moreover, would it be possible to enable Sage-doc mode as a minor mode when looking at this documentation, or is there a better solution?

I think it is not difficult to define such a minor-mode only for Sage documentation.

So, is it possible to visit an info node by typing "object?"?

To visit a node or document for an object, the info file name is necessary. For example, the corresponding file name for the object ZZ is "sagereferencemanualstandardcommutativerings.info".

Do you know how to implement a Python function that receive an object and returns the corresponding file name?

[mantepse]

I have now understood how the filename for the texi and info files are generated, this is done in src/doc/en/reference/conf_sub.py. Adding

texinfo_documents = [
('index', name, title, u'The Sage Development Team', project, 'The ' + title + ' manual', 'SageMath')
]

(see http://www.sphinx-doc.org/en/1.4.8/config.html) yields, for example for the manifolds directory, a file manifolds.texi with the following header:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename manifolds.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 1.4.4.@*
@end ifinfo
@settitle Manifolds
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory SageMath
@direntry
* Sage Reference Manual; Manifolds: (manifolds.info). The Manifolds manual
@end direntry

[mantepse]

I still don't know how to extract the source filename (eg.,src/sage/manifolds/manifold.py when you do object??. In fact, I don't know how sage-shell-mode does this.

[mantepse]

I'm pushing my changes to trac, because reading sage-shell-mode.el it appears to me that you might know how to continue.

[stakemori]

I still don't know how to extract the source filename (eg.,src/sage/manifolds/manifold.py when you do object??. In fact, I don't know how sage-shell-mode does this.

sage-shell-mode uses sage.misc.sageinspect.sage_getfile(object) for that purpose.

I think for a given object, sage-shell-mode has to search the module name that provides the object in rst files in sub-directories of src/doc/en/reference. For example, sage/rings/integer_ring is written in src/doc/en/reference/rings_standard/index.rst. It seems that these rst files are written by hand. So I guess there doesn't exist a canonical way to search module names in these files.

[mantepse]

Just let me know what filename would be good for you.

[stakemori]

Currently, you use the directory name for the filename. The directory name is OK. Thanks.

For a given object, it is possible to know the module name that defines the object. Then by parsing index.rst files in src/doc/en/reference, it is also possible to know the corresponding directory name for the object. So I think I can implement the function I wrote above.

[mantepse]

I could probably also install all info files into a single directory, would this be better?

I have never prepared a texinfo manual before, so any comments are appreciated.

[stakemori]

I could probably also install all info files into a single directory, would this be better?

Yes, I guess it would be better. Thanks.

[mantepse]

I'm afraid the idea of moving all info manuals into one directory might not be so good after all, but I'm not sure: could it be that we create a name conflict that way (that is, two info manuals of the same name, which originally were in different directories)?

[stakemori]

Info file names are same as names of sub directories in src/doc/en/reference, aren't they? So I guess name conflicts could not happen. I might misunderstand the word "all info files".

[mantepse]

I thought it might happen that there are also sub-sub directories. (Currently it does not...)

[stakemori]

I think all info files in INFOPATH (or Info-default-directory-list, Info-directory-list, Info-additional-directory-list) should have different names. So info files in different directories should not have the same name.

I said the directory name is OK. But it was wrong, sorry. It would be better to add a prefix (for example sage_reference) to avoid name conflicts with info files provided by other software.

[stakemori]

I just added sage-shell-info. It is similar to M-x info, but it highlights some keywords and adds some keybindings (C-c C-d and C-c C-z).

I haven't implemented obejct? yet.