Re: [sage-devel] High level architectural design document of Sage

2012-12-10 Thread Harald Schilly 

On Monday, December 10, 2012 9:02:17 PM UTC+1, Harald Schilly wrote:
>
> I could also envision some meta-tutorials, that explain what could be done 
> for a certain problem...


... after having some thoughts about this, I remembered this: The "R" 
program is rather small, but all the features are available in packages. 
The usual question is, which one of those thousands does what I want? They 
have a "Task oriented" overview page over here:
http://cran.rstudio.com/web/views/
I don't think we should actually copy this scheme, but it is certainly a 
nice idea. There, you have topics and sub-topics with some explanations. 
>From there, you can jump to specific pages or some tutorial pages (like we 
already have).
And to repeat what I've already written, I think it could be helpful to 
have a utility script that generates the necessary sphinx pages for those 
pages automatically, based on some annotations (or whatever) in the pages 
themselves. This would make it easy to keep this consistent and so on.

H

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-10 Thread Harald Schilly 


On Monday, December 3, 2012 10:45:50 PM UTC+1, William wrote:
>
> If anybody reading this has any experience with how to dramatically 
> improve reference documentation of a big open source software project, 
> please share.
>

Likely, there is nobody in the world. My take on this would be to start 
small and iterate. The thematic tutorials are nice, but would only fit into 
chapters and sub-chapters of some larger collection. Also, a strict 
hierarchical system won't work in my eyes, because a certain sub-topic  
should be accessible through different hierarchical paths. I could also 
envision some meta-tutorials, that explain what could be done for a certain 
problem (different ways of how a polynomial system can be solved, based on 
the ring and so on).
Is it possible to organize documents in sphinx via tags or categories? 
Maybe we have to start to invent a utility script, that creates index and 
sub-index pages for sphinx, which collect and organize documents based on 
tags in them. 
The effect of this would be, that a novice user doesn't need to actively 
search through the functions (as they are in the sources), but could look 
at a list of high-level topics. Then, the sub-topics (with some 
description?) guide him/her to a specific tutorials. Clearly, this is just 
a rough idea and needs much more brainstorming :-)

Harald

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: Re: [sage-devel] High level architectural design document of Sage

2012-12-04 Thread John Cremona 
On 4 December 2012 13:44, William Stein  wrote:
>

>
> Does anybody want to organize another doc days (maybe to happen in July
> 2013?)?
>

Note that there's a planned Sage Days in Leiden at the end of that
month:  
http://www.lorentzcenter.nl/lc/web/2013/571/info.php3?wsid=571&venue=Snellius
 subtitled "Algorithms in Arithmetic Geometry" .

John

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: Re: [sage-devel] High level architectural design document of Sage

2012-12-04 Thread William Stein 
On Dec 4, 2012 2:56 AM, "Martin Albrecht" 
wrote:
>
> > Yes, it was kind of frustrating.  Basically, David advertised it a
> > lot, but at the end of the day, basically few people were available to
> > come to a Sage Days on improving the documentation, even with all
> > expenses paid...
>
> I don't know if my situation is typical but for me usually the time
between
> announcement and workshop is too short. The e-mail for doc days went out
on
> Feb 5 and it was scheduled for April 17-22. Usually, my plans are fixed
for 3+
> months in advance and I cannot squeeze in long distance travel on such a
> "short" notice.
>
> Sorry for going slightly off topic.
>

Does anybody want to organize another doc days (maybe to happen in July
2013?)?

> Cheers,
> Martin
>
> --
> name: Martin Albrecht
> _pgp: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99
> _otr: 47F43D1A 5D68C36F 468BAEBA 640E8856 D7951CCF
> _www: http://martinralbrecht.wordpress.com/
> _jab: martinralbre...@jabber.ccc.de
>
> --
> You received this message because you are subscribed to the Google Groups
"sage-devel" group.
> To post to this group, send email to sage-devel@googlegroups.com.
> To unsubscribe from this group, send email to
sage-devel+unsubscr...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel?hl=en.
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-04 Thread Johannes 
Something  like the information provided at
http://www.sagemath.org/doc/thematic_tutorials/tutorial-objects-and-classes.html#sage-specifics-about-classes
would be nice to have for an mathematical object in general. A good
start would be the blog post at sagemath.blogspot.com from William,
explaining the coercion model:
http://sagemath.blogspot.de/2010/11/brief-history-and-motivation-behind.html
I think it is the wrong way, that somebody who wants to start coding for
sage  must have to look at the source code to get a to learn something
about the design and structure of sage.

greatz
Johannes

On 04.12.2012 05:18, Michael Orlitzky wrote:
> On 12/03/2012 04:45 PM, William Stein wrote:
>>
>> Yes, it was kind of frustrating.  Basically, David advertised it a
>> lot, but at the end of the day, basically few people were available to
>> come to a Sage Days on improving the documentation, even with all
>> expenses paid...
>>
>> If anybody reading this has any experience with how to dramatically
>> improve reference documentation of a big open source software project,
>> please share. One difficulty with Sage is that there is probably
>> no human alive who can really understand all of what Sage does, due to
>> how many areas of advanced mathematics Sage touches, so whatever we do
>> simply can't be a one-person project.  In this regard, the scope
>> of Magma is actually much smaller than that of Sage, since, e.g.,
>> Magma includes nothing in symbolic calculus and almost nothing in
>> numerical analysis, which are two massive areas.
>>
>> Somebody asserted above that the Sage reference manual is supposed to
>> cover "all the functionality of Sage".  However, this is not what it
>> does, and I'm not sure it should.  The reference manual covers most of
>> the functionality of the core Sage library, which -- depending on your
>> perspective -- may or may not be a big part of what Sage does (for
>> you).  For example, an undergrad recently asked me how to find out
>> about what Sage can do in signal processing, and I definitely didn't
>> suggest that he read the Sage reference manual; instead, I suggested
>> the scipy website.   Another example: Cython is a big part of Sage,
>> but it isn't documented in the reference manual.
>>
> 
> The existing thematic tutorials sort-of address this problem:
> 
>   http://www.sagemath.org/doc/thematic_tutorials/
> 
> but there are far too few of them. I would suggest creating a magma-like
> hierarchy of thematic tutorials, one for each branch that Sage supports.
> 
> The tutorials could link to individual pages of the reference manual,
> and should go through most common tasks that people might want to do. It
> should also have brief translations for users of other CAS software. See
> Rosetta Code  for an example of this done well.
> 

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: Re: [sage-devel] High level architectural design document of Sage

2012-12-04 Thread Martin Albrecht 
> Yes, it was kind of frustrating.  Basically, David advertised it a
> lot, but at the end of the day, basically few people were available to
> come to a Sage Days on improving the documentation, even with all
> expenses paid...

I don't know if my situation is typical but for me usually the time between 
announcement and workshop is too short. The e-mail for doc days went out on 
Feb 5 and it was scheduled for April 17-22. Usually, my plans are fixed for 3+ 
months in advance and I cannot squeeze in long distance travel on such a 
"short" notice.

Sorry for going slightly off topic.

Cheers,
Martin

--
name: Martin Albrecht
_pgp: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99
_otr: 47F43D1A 5D68C36F 468BAEBA 640E8856 D7951CCF
_www: http://martinralbrecht.wordpress.com/
_jab: martinralbre...@jabber.ccc.de

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-03 Thread Michael Orlitzky 
On 12/03/2012 04:45 PM, William Stein wrote:
> 
> Yes, it was kind of frustrating.  Basically, David advertised it a
> lot, but at the end of the day, basically few people were available to
> come to a Sage Days on improving the documentation, even with all
> expenses paid...
> 
> If anybody reading this has any experience with how to dramatically
> improve reference documentation of a big open source software project,
> please share. One difficulty with Sage is that there is probably
> no human alive who can really understand all of what Sage does, due to
> how many areas of advanced mathematics Sage touches, so whatever we do
> simply can't be a one-person project.  In this regard, the scope
> of Magma is actually much smaller than that of Sage, since, e.g.,
> Magma includes nothing in symbolic calculus and almost nothing in
> numerical analysis, which are two massive areas.
> 
> Somebody asserted above that the Sage reference manual is supposed to
> cover "all the functionality of Sage".  However, this is not what it
> does, and I'm not sure it should.  The reference manual covers most of
> the functionality of the core Sage library, which -- depending on your
> perspective -- may or may not be a big part of what Sage does (for
> you).  For example, an undergrad recently asked me how to find out
> about what Sage can do in signal processing, and I definitely didn't
> suggest that he read the Sage reference manual; instead, I suggested
> the scipy website.   Another example: Cython is a big part of Sage,
> but it isn't documented in the reference manual.
> 

The existing thematic tutorials sort-of address this problem:

  http://www.sagemath.org/doc/thematic_tutorials/

but there are far too few of them. I would suggest creating a magma-like
hierarchy of thematic tutorials, one for each branch that Sage supports.

The tutorials could link to individual pages of the reference manual,
and should go through most common tasks that people might want to do. It
should also have brief translations for users of other CAS software. See
Rosetta Code  for an example of this done well.

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-03 Thread William Stein 
,

On Mon, Dec 3, 2012 at 1:16 PM, David Roe  wrote:
>
>
>
> On Sun, Dec 2, 2012 at 11:59 PM, charles Bouillaguet
>  wrote:
>>
>> I still think that MAGMA's "handbook" is easier to browse than SAGE's
>> reference manual (both are supposed to exhaustively describe all the
>> functions in the system). One reason for that is probably that in
>> SAGE, we auto-generate the manual...
>>
>> But still, there might be a few things we could do to help, e.g.
>> #6495. My generic opinion is that the most frequently used
>> mathematical objects should be the easiest to find in  the reference
>> manual (think of it as Huffman coding...).
>>
>> For instance, it is close to impossible to find "vector spaces" in the
>> reference manual. This has puzzled and annoyed me for a while! I now
>> realize that this is because we don't have a "VectorSpace" class, and
>> that we instead have "FreeModules", which are more generic. The thing
>> is that most, if not all, undergrads looking to play with vector
>> spaces will not know that they should in fact look for FreeModule's.
>> Wouldn't it be possible to work around that, and make the reference
>> manual a bit more "non-advanced-mathematicians-friendly" ?
>>
>> Comparing with the MAGMA handbook again, I think that their design
>> decision to expose "basic rings and linear algebra" as one of the
>> first titles of their manual is a very good one. It has certainly
>> helped me learning MAGMA quickly...
>
>
> I agree that MAGMA's manual is much better structured than Sage's.  Last
> spring William funded a Sage Days on improving Sage's documentation; one of
> the main goals was to think about how Sage's documentation was presented.
> Unfortunately, we had very few people willing and able to attend and the

Yes, it was kind of frustrating.  Basically, David advertised it a
lot, but at the end of the day, basically few people were available to
come to a Sage Days on improving the documentation, even with all
expenses paid...

If anybody reading this has any experience with how to dramatically
improve reference documentation of a big open source software project,
please share. One difficulty with Sage is that there is probably
no human alive who can really understand all of what Sage does, due to
how many areas of advanced mathematics Sage touches, so whatever we do
simply can't be a one-person project.  In this regard, the scope
of Magma is actually much smaller than that of Sage, since, e.g.,
Magma includes nothing in symbolic calculus and almost nothing in
numerical analysis, which are two massive areas.

Somebody asserted above that the Sage reference manual is supposed to
cover "all the functionality of Sage".  However, this is not what it
does, and I'm not sure it should.  The reference manual covers most of
the functionality of the core Sage library, which -- depending on your
perspective -- may or may not be a big part of what Sage does (for
you).  For example, an undergrad recently asked me how to find out
about what Sage can do in signal processing, and I definitely didn't
suggest that he read the Sage reference manual; instead, I suggested
the scipy website.   Another example: Cython is a big part of Sage,
but it isn't documented in the reference manual.

 -- William

> workshop was repurposed on p-adic overconvergent modular symbols.  :-)
>
> I suspect that if there was interest in running a Sage Days on improving the
> structure of Sage's documentation we could find funding.
> David
>
> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To post to this group, send email to sage-devel@googlegroups.com.
> To unsubscribe from this group, send email to
> sage-devel+unsubscr...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel?hl=en.
>
>



-- 
William Stein
Professor of Mathematics
University of Washington
http://wstein.org

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-03 Thread David Roe 
On Sun, Dec 2, 2012 at 11:59 PM, charles Bouillaguet <
charles.bouillag...@gmail.com> wrote:

> I still think that MAGMA's "handbook" is easier to browse than SAGE's
> reference manual (both are supposed to exhaustively describe all the
> functions in the system). One reason for that is probably that in
> SAGE, we auto-generate the manual...
>
> But still, there might be a few things we could do to help, e.g.
> #6495. My generic opinion is that the most frequently used
> mathematical objects should be the easiest to find in  the reference
> manual (think of it as Huffman coding...).
>
> For instance, it is close to impossible to find "vector spaces" in the
> reference manual. This has puzzled and annoyed me for a while! I now
> realize that this is because we don't have a "VectorSpace" class, and
> that we instead have "FreeModules", which are more generic. The thing
> is that most, if not all, undergrads looking to play with vector
> spaces will not know that they should in fact look for FreeModule's.
> Wouldn't it be possible to work around that, and make the reference
> manual a bit more "non-advanced-mathematicians-friendly" ?
>
> Comparing with the MAGMA handbook again, I think that their design
> decision to expose "basic rings and linear algebra" as one of the
> first titles of their manual is a very good one. It has certainly
> helped me learning MAGMA quickly...
>

I agree that MAGMA's manual is much better structured than Sage's.  Last
spring William funded a Sage Days on improving Sage's documentation; one of
the main goals was to think about how Sage's documentation was presented.
Unfortunately, we had very few people willing and able to attend and the
workshop was repurposed on p-adic overconvergent modular symbols.  :-)

I suspect that if there was interest in running a Sage Days on improving
the structure of Sage's documentation we could find funding.
David

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-03 Thread Volker Braun 
On Sunday, December 2, 2012 8:52:00 PM UTC-5, John H Palmieri wrote:

> See 
> http://sage.math.washington.edu/home/palmieri/misc/6495-jsmath/html/en/reference/index.htmlfor
>  what the reference manual might look like if 
> http://trac.sagemath.org/sage_trac/ticket/6495 is every merged into Sage.


Looks much nicer than the current one, thanks for working on this!

Florent, are you still reviewing that ticket?

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-02 Thread charles Bouillaguet 
2012/12/3 John H Palmieri :
> See
> http://sage.math.washington.edu/home/palmieri/misc/6495-jsmath/html/en/reference/index.html
> for what the reference manual might look like if
> http://trac.sagemath.org/sage_trac/ticket/6495 is every merged into Sage. Do
> you like that any better?

I do ! I think it would help to make SAGE easier to get acquainted
with (especially for people like me accustomed to another CAS).

My next remarks may be more a matter of personal taste. I used to
teach Maple to undergrads, and I use a specific subset of SAGE
functionnality on a daily basus, so that I may be a bit biased.

I still think that MAGMA's "handbook" is easier to browse than SAGE's
reference manual (both are supposed to exhaustively describe all the
functions in the system). One reason for that is probably that in
SAGE, we auto-generate the manual...

But still, there might be a few things we could do to help, e.g.
#6495. My generic opinion is that the most frequently used
mathematical objects should be the easiest to find in  the reference
manual (think of it as Huffman coding...).

For instance, it is close to impossible to find "vector spaces" in the
reference manual. This has puzzled and annoyed me for a while! I now
realize that this is because we don't have a "VectorSpace" class, and
that we instead have "FreeModules", which are more generic. The thing
is that most, if not all, undergrads looking to play with vector
spaces will not know that they should in fact look for FreeModule's.
Wouldn't it be possible to work around that, and make the reference
manual a bit more "non-advanced-mathematicians-friendly" ?

Comparing with the MAGMA handbook again, I think that their design
decision to expose "basic rings and linear algebra" as one of the
first titles of their manual is a very good one. It has certainly
helped me learning MAGMA quickly...

Charles

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-02 Thread Travis Scrimshaw 
Hey everyone,
   Two things on that note, I looked over the conventions page and noticed 
some discrepancies, which is now ticket 
http://trac.sagemath.org/sage_trac/ticket/13791 and I'd appreciate review. 
Second, Andrea, there are many bugs which are not mathematical problems, 
but errors in code/documentation, such as corner cases not checked or not 
robust enough (#11506, #12871, #9129, there are many others).

Best,
Travis


On Sunday, December 2, 2012 10:22:44 AM UTC-8, Volker Braun wrote:
>
> Your starting point should be the developer guide (
> http://www.sagemath.org/doc/developer), not the reference manual. The 
> latter is really for reference. I think the developer manual has a 
> reasonable explanation of the coercion model. A similar treatment of the 
> category framework is sorely lacking, I agree. It would be really great if 
> one of the people who was involved in writing it would step forward and add 
> a similar section to the developer guide.
>
> To further flesh out the developer guide, maybe we should include a 
> careful selection of module docstrings? By that I mean only the first 
> docstring in the module, ignoring all the class/function specific 
> docstrings. Some module docstrings are really written to give a high-level 
> overview and by cherry-picking those. I'm not sure if sphinx lets us 
> currently do that, though.
>
>
>
> On Sunday, December 2, 2012 12:43:49 PM UTC-5, Charles Bouillaguet wrote:
>>
>> Actually, I think I agree with the request of WM Chung. I found myself 
>> longing for a high-level overview of SAGE development. I think it 
>> could be pretty simple, but that it could explain how some things are 
>> organized. For instance : 
>>
>> *) what is the category framework? what purpose does it serve? How 
>> should it (in theory) interact with the rest of the code? 
>>
>> *) What is the rationale behind the class hierarchy? (mathematical 
>> sub-concept?) 
>>
>> *) A pointer to the document somewhere that explains the 
>> coercion/conversion framework. 
>>
>>
>> And now, for something completely different. 
>>
>> I think that the reference manual is very useful, but its linear 
>> structure (a loong list of items where it is not obvious where to 
>> find what you are looking for) is a bit baffling for beginners. I come 
>> from the MAGMA community, and I tend to think that the hierarchical 
>> structure of the MAGMA reference manual is a bit easier to navigate 
>> (http://magma.maths.usyd.edu.au/magma/handbook/). I could try to 
>> propose a patch implementing such a structure if someone thinks its 
>> worth it... 
>>
>> Also, the presence of the category framework in the reference manual 
>> is also a bit confusing. For instance, when I was new to SAGE, I 
>> wanted to write something that manipulated vector spaces. I thus 
>> browsed the reference manual, and naturally found the "Vector Space" 
>> category... where, of course, I could not find the functions I was 
>> looking for. Why not remove the categories from the reference manual? 
>> What purpose do they serve? 
>>
>>

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-02 Thread John H Palmieri 


On Sunday, December 2, 2012 9:43:49 AM UTC-8, Charles Bouillaguet wrote:
>
>
> And now, for something completely different. 
>
> I think that the reference manual is very useful, but its linear 
> structure (a loong list of items where it is not obvious where to 
> find what you are looking for) is a bit baffling for beginners. I come 
> from the MAGMA community, and I tend to think that the hierarchical 
> structure of the MAGMA reference manual is a bit easier to navigate 
> (http://magma.maths.usyd.edu.au/magma/handbook/). I could try to 
> propose a patch implementing such a structure if someone thinks its 
> worth it... 
>

See 
http://sage.math.washington.edu/home/palmieri/misc/6495-jsmath/html/en/reference/index.html
 
for what the reference manual might look like if 
http://trac.sagemath.org/sage_trac/ticket/6495 is every merged into Sage. 
Do you like that any better?

-- 
John

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-02 Thread Volker Braun 
Your starting point should be the developer guide 
(http://www.sagemath.org/doc/developer), not the reference manual. The 
latter is really for reference. I think the developer manual has a 
reasonable explanation of the coercion model. A similar treatment of the 
category framework is sorely lacking, I agree. It would be really great if 
one of the people who was involved in writing it would step forward and add 
a similar section to the developer guide.

To further flesh out the developer guide, maybe we should include a careful 
selection of module docstrings? By that I mean only the first docstring in 
the module, ignoring all the class/function specific docstrings. Some 
module docstrings are really written to give a high-level overview and by 
cherry-picking those. I'm not sure if sphinx lets us currently do that, 
though.



On Sunday, December 2, 2012 12:43:49 PM UTC-5, Charles Bouillaguet wrote:
>
> Actually, I think I agree with the request of WM Chung. I found myself 
> longing for a high-level overview of SAGE development. I think it 
> could be pretty simple, but that it could explain how some things are 
> organized. For instance : 
>
> *) what is the category framework? what purpose does it serve? How 
> should it (in theory) interact with the rest of the code? 
>
> *) What is the rationale behind the class hierarchy? (mathematical 
> sub-concept?) 
>
> *) A pointer to the document somewhere that explains the 
> coercion/conversion framework. 
>
>
> And now, for something completely different. 
>
> I think that the reference manual is very useful, but its linear 
> structure (a loong list of items where it is not obvious where to 
> find what you are looking for) is a bit baffling for beginners. I come 
> from the MAGMA community, and I tend to think that the hierarchical 
> structure of the MAGMA reference manual is a bit easier to navigate 
> (http://magma.maths.usyd.edu.au/magma/handbook/). I could try to 
> propose a patch implementing such a structure if someone thinks its 
> worth it... 
>
> Also, the presence of the category framework in the reference manual 
> is also a bit confusing. For instance, when I was new to SAGE, I 
> wanted to write something that manipulated vector spaces. I thus 
> browsed the reference manual, and naturally found the "Vector Space" 
> category... where, of course, I could not find the functions I was 
> looking for. Why not remove the categories from the reference manual? 
> What purpose do they serve? 
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

Re: [sage-devel] High level architectural design document of Sage

2012-12-02 Thread charles Bouillaguet 
Hi,

Actually, I think I agree with the request of WM Chung. I found myself
longing for a high-level overview of SAGE development. I think it
could be pretty simple, but that it could explain how some things are
organized. For instance :

*) what is the category framework? what purpose does it serve? How
should it (in theory) interact with the rest of the code?

*) What is the rationale behind the class hierarchy? (mathematical sub-concept?)

*) A pointer to the document somewhere that explains the
coercion/conversion framework.


And now, for something completely different.

I think that the reference manual is very useful, but its linear
structure (a loong list of items where it is not obvious where to
find what you are looking for) is a bit baffling for beginners. I come
from the MAGMA community, and I tend to think that the hierarchical
structure of the MAGMA reference manual is a bit easier to navigate
(http://magma.maths.usyd.edu.au/magma/handbook/). I could try to
propose a patch implementing such a structure if someone thinks its
worth it...

Also, the presence of the category framework in the reference manual
is also a bit confusing. For instance, when I was new to SAGE, I
wanted to write something that manipulated vector spaces. I thus
browsed the reference manual, and naturally found the "Vector Space"
category... where, of course, I could not find the functions I was
looking for. Why not remove the categories from the reference manual?
What purpose do they serve?

Cheers,

2012/12/1 Wai Man Chung :
> Hi,
>
> I am new to Sage and I am interested to participate in the development work
> of Sage. I would like to understand the codes of Sage.
>
> I would like to know if there is any high level architectural design
> document on Sage. I can find fragments of information related to this, e.g.
> -  Sage use some other software components like GAP,
> -  Sage use languages like C/C++, Python, etc,
> -  Sage has object-oriented approach in coding ;
> -  Sage has many functional module like Calculus, algebra, etc.
>
> Is there any high level architectural diagram showing the inter-relationship
> among these ? e.g. Inheritance tree of the object hierarchy, dependency
> among the software components, e.g. a certain functional module may have
> used some software components, etc. I think such document is helpful to
> beginner.
>
> As a beginner, can anyone share some experience on the way to trace the
> codes ? e.g. when I see from tutorial or reference manual on some functions,
> any ways to look for the corresponding source codes ? (by searching the text
> pattern, etc.)  Or in the other way round, when I look at the source code,
> any way to know how to use and run it at sage ?
>
> Thanks in advance.
> WM Chung
>
>
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To post to this group, send email to sage-devel@googlegroups.com.
> To unsubscribe from this group, send email to
> sage-devel+unsubscr...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel?hl=en.
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.

[sage-devel] High level architectural design document of Sage

2012-11-30 Thread Wai Man Chung 
Hi,

I am new to Sage and I am interested to participate in the development work 
of Sage. I would like to understand the codes of Sage.

I would like to know if there is any high level architectural design 
document on Sage. I can find fragments of information related to this, e.g. 
-  Sage use some other software components like GAP, 
-  Sage use languages like C/C++, Python, etc, 
-  Sage has object-oriented approach in coding ; 
-  Sage has many functional module like Calculus, algebra, etc. 

Is there any high level architectural diagram showing the 
inter-relationship among these ? e.g. Inheritance tree of the object 
hierarchy, dependency among the software components, e.g. a certain 
functional module may have used some software components, etc. I think such 
document is helpful to beginner. 

As a beginner, can anyone share some experience on the way to trace the 
codes ? e.g. when I see from tutorial or reference manual on some 
functions, any ways to look for the corresponding source codes ? (by 
searching the text pattern, etc.)  Or in the other way round, when I look 
at the source code, any way to know how to use and run it at sage ? 

Thanks in advance. 
WM Chung




-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To post to this group, send email to sage-devel@googlegroups.com.
To unsubscribe from this group, send email to 
sage-devel+unsubscr...@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel?hl=en.