ASKSAGE: Sage Q&A Forum - Individual question feedhttp://ask.sagemath.org/questions/Q&A Forum for SageenCopyright Sage, 2010. Some rights reserved under creative commons license.Sun, 04 Nov 2012 11:14:17 -0600Atomatic building of documentation for a custom libraryhttp://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/Hi there,
I have created a .sage file with functions of my own, and have documented every function following http://www.sagemath.org/doc/developer/conventions.html#documentation-strings
Is there a way of generating automatically a *pdf* or *html* with the docstring of every function in the library, such as the ones in the sage documentation?
Or, more or less the same: can I use something like 'sage -docbuild' for a custom file (with standard doctrings)?
Cheers!Wed, 31 Oct 2012 04:36:59 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/Comment by kcrisman for <p>Hi there,</p>
<p>I have created a .sage file with functions of my own, and have documented every function following <a href="http://www.sagemath.org/doc/developer/conventions.html#documentation-strings">http://www.sagemath.org/doc/developer...</a></p>
<p>Is there a way of generating automatically a <em>pdf</em> or <em>html</em> with the docstring of every function in the library, such as the ones in the sage documentation?</p>
<p>Or, more or less the same: can I use something like 'sage -docbuild' for a custom file (with standard doctrings)?</p>
<p>Cheers!</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18767#post-id-18767Well, it *is* possible if you add your file to your Sage installation (presumably as a .py file?) and then add it to the list of things in the reference manual. But I think you mean as a separate file.Fri, 02 Nov 2012 04:53:36 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18767#post-id-18767Comment by Jesustc for <p>Hi there,</p>
<p>I have created a .sage file with functions of my own, and have documented every function following <a href="http://www.sagemath.org/doc/developer/conventions.html#documentation-strings">http://www.sagemath.org/doc/developer...</a></p>
<p>Is there a way of generating automatically a <em>pdf</em> or <em>html</em> with the docstring of every function in the library, such as the ones in the sage documentation?</p>
<p>Or, more or less the same: can I use something like 'sage -docbuild' for a custom file (with standard doctrings)?</p>
<p>Cheers!</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18763#post-id-18763I do, thanks.Fri, 02 Nov 2012 05:57:02 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18763#post-id-18763Answer by John Palmieri for <p>Hi there,</p>
<p>I have created a .sage file with functions of my own, and have documented every function following <a href="http://www.sagemath.org/doc/developer/conventions.html#documentation-strings">http://www.sagemath.org/doc/developer...</a></p>
<p>Is there a way of generating automatically a <em>pdf</em> or <em>html</em> with the docstring of every function in the library, such as the ones in the sage documentation?</p>
<p>Or, more or less the same: can I use something like 'sage -docbuild' for a custom file (with standard doctrings)?</p>
<p>Cheers!</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?answer=14130#post-id-14130I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.Thu, 01 Nov 2012 07:32:07 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?answer=14130#post-id-14130Comment by kcrisman for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18766#post-id-18766I wouldn't imagine it would be that hard, if we could just automate the sphinx quickstart thing to add the files and then do whatever magic extracts the function definitions in Sage's ReST format. I'd be very open to reviewing any work you do on that ;)Fri, 02 Nov 2012 04:54:48 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18766#post-id-18766Comment by Jesustc for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18749#post-id-18749That's beyond wonderful! Unfortunately, I have encountered some problems after applying the patch: (1) 'autodoc can't import/find module ...', so where should I put the file?; and (2) the file name contains an underscore, which sphinxs is treating like a math subscript. But, really, thanks for the quick solution! :)
Sun, 04 Nov 2012 08:27:36 -0600http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18749#post-id-18749Comment by Jesustc for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18748#post-id-18748Finally worked: I had to run it from the sage shell, rename the file to a .py (it was .sage) and add the corresponding path to the $PYTHONPATH of the sage shell. Interestingly, a couple of spurious functions that were not in the module did appear in the documentation. Cheers!Sun, 04 Nov 2012 11:14:17 -0600http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18748#post-id-18748Comment by John Palmieri for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18760#post-id-18760See also http://trac.sagemath.org/sage_trac/ticket/13679. This works for me with .py and .sage files, but not with .pyx files.Fri, 02 Nov 2012 08:28:18 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18760#post-id-18760Comment by John Palmieri for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18765#post-id-18765I've been playing with it for the last day. I may have something soon. One issue is to decide where to do the building; I think it makes most sense to do everything in the user's .sage directory.Fri, 02 Nov 2012 05:17:36 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18765#post-id-18765Comment by Jesustc for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18764#post-id-18764Shame on me: http://ask.sagemath.org/question/432/using-sphinx-to-document-a-module-using-sage. Still, I would say it is not a perfect solution.Fri, 02 Nov 2012 05:44:08 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18764#post-id-18764Comment by kcrisman for <p>I don't think this is possible now, but it's an interesting idea. I wonder how hard it would be to implement.</p>
http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18762#post-id-18762I had a feeling, but was also too lazy... not perfect, but certainly doable.Fri, 02 Nov 2012 07:47:18 -0500http://ask.sagemath.org/question/9487/atomatic-building-of-documentation-for-a-custom-library/?comment=18762#post-id-18762