Hello !
> Despite from that I hope you understand what I have in mind with developer
> documentation.
I totally agree with you on this respect. The documentation that Jori
wanted to write totally fits with your example: there is a class that
we did not write ourselves and that we do not understan
> Again it depends on the case. Not every algorithm needs to be documented,
> some things are necessarily assumed to be known to anybody who wants to
> make relevant changes. I don't think Sage explains the algorithm for
> solving CRT anywhere...
>
Agree. I did not have in mind well-known alg
On Monday, January 5, 2015 5:45:21 PM UTC+1, Jakob Kroeker wrote:
> class diagrams, state transition diagrams, internal code
> interdependencies/implemented design patterns, call graphs
How is the class hierarchy not best described by the code? If you can't be
bothered to read the code you ca
>
> I don't understand what you mean by "design". If you code isn't readable
> then that can't be fixed by documentation, only by writing clear code.
>
The program architecture, the grand picture (if not obvious): class
diagrams, state transition diagrams, internal code
interdependencies/imp
On Monday, January 5, 2015 3:15:07 PM UTC+1, Jakob Kroeker wrote:
>
> Does the 'why' implicate documentation for an abstract description of the
>> implementation design
>
>
I don't understand what you mean by "design". If you code isn't readable
then that can't be fixed by documentation, only by
>
> * Document the why, not the how
>
Does the 'why' implicate documentation for an abstract description of the
implementation design (if not obvious) and the (reference to) underlying
algorithms?
I just looked at the sage review checklist and did not find and advice to
check for appropriate
> The __init__ docstring is used as the class docstring if there is no
> separate class docstring, this is what I would recommend if you want it
> seen. Alternatively you can force sphinx to show it with a .. automethod:
> instruction.
>
>
Perhaps there should be a mention of this in the devel
The __init__ docstring is used as the class docstring if there is no
separate class docstring, this is what I would recommend if you want it
seen. Alternatively you can force sphinx to show it with a .. automethod:
instruction.
As for what is appropriate to document, the usual adages apply:
*
On Sunday, January 4, 2015 2:20:56 PM UTC-8, Andrew wrote:
>
> I agree with Nathan that it would be good to have "internal" documentation
> more accessible (and to write more of it). I don't see any issues with
> "scaring" ordinary users as this material should be in the developers
> manual rat
I agree with Nathan that it would be good to have "internal" documentation
more accessible (and to write more of it). I don't see any issues with
"scaring" ordinary users as this material should be in the developers
manual rather than the reference manual.
At the moment we are writing a lot of
On Sat, 27 Dec 2014, Travis Scrimshaw wrote:
If you're developing, you're...not...looking at the code? That's how I'm
interpreting your comments.
Is there "internal" documentation in Sage? If so, where it is?
I mean that if a developer wants to know how some class is made (and maybe
WHY, if
> Is it possible to make sphinx generate html code that is "hidden" with a
> toggle button when it encounter a "Technical details::" section? That could
> be a good compromise solution.
Funny that you ask. This is what I wrote to Sphinx-devel 10 days ago:
https://groups.google.com/d/topic/sphinx-u
Is it possible to make sphinx generate html code that is "hidden" with a
toggle button when it encounter a "Technical details::" section? That could
be a good compromise solution.
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe fr
There is still one possibility: Having a file for *only* internal
documentation or technical details. Then
http://www.sagemath.org/doc/reference/combinat/posets.html would contain
something like "Implementation details" as a list item.
Also some user might benefit from technical details. Some
> If you're developing, you're...not...looking at the code? That's how I'm
> interpreting your comments. I don't see how it is possible to develop
> without looking at the code.
>
> To reiterate, public documentation should be there for the user, internal
> documentation (i.e. private methods) and
If you're developing, you're...not...looking at the code? That's how I'm
interpreting your comments. I don't see how it is possible to develop
without looking at the code.
To reiterate, public documentation should be there for the user, internal
documentation (i.e. private methods) and comments
> That is few and far between, and putting it at the module or class levels
> are quite intrusive.
In a section named "technical details", you would find this intrusive ?
> Having the background technical information
> (especially that about design patterns used or easily deciphered from the
> co
>
> Well, our users can become developpers too. Plus we can show this in a
> non-intrusive way. It is a bit hard to make all the doc "clean" when
> it is just code.
>
That is few and far between, and putting it at the module or class levels
are quite intrusive.
>
> Look at this: the doc is
Yo !
>-1 as it is internal workings and would add useless information to the
> average user. If you need to know those details, then you should be looking
> at the file/code. IMO the public documentation should be about the
> mathematical structure and how to use the class in Sage.
Well, our
Hey,
-1 as it is internal workings and would add useless information to the
average user. If you need to know those details, then you should be looking
at the file/code. IMO the public documentation should be about the
mathematical structure and how to use the class in Sage.
Best,
Travis
O
+1 for making it appear at the end of the module's doc. That will be more
visible than in the __init__ function or the main class itself, which may
appear at random places in the html page.
Nathann
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group
21 matches
Mail list logo
