[PATCH 0 of 3] Documentation polishing
Ondrej Certik
Kirill Smelkov
> # HG changeset patch
> # User Ondrej Certik <ond...@certik.cz>
> # Date 1213705032 -7200
> # Node ID 04a669f38bb24e9afc7166a414d5b53327c8fb74
> # Parent 26fae53aa09a3f513836ad081f54948230eace4d
> Use Sphinx 0.3
>
> diff --git a/doc/Makefile b/doc/Makefile
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -4,7 +4,7 @@ RST2HTML = rst2html
>
> # You can set these variables from the command line.
> SPHINXOPTS =
> -SPHINXVER = 0.1.61843
> +SPHINXVER = 0.3
> SPHINXBUILDpy = sphinx/Sphinx-$(SPHINXVER)/sphinx-build.py
> SPHINXBUILD = python $(SPHINXBUILDpy)
> PAPER =
Why not?
Thanks and sorry for the delay.
--
Всего хорошего, Кирилл.
Kirill Smelkov
> # HG changeset patch
> # User Ondrej Certik <ond...@certik.cz>
> # Node ID 26fae53aa09a3f513836ad081f54948230eace4d
> # Parent 2c92cefdd78ea34f070c97063802c92ef97fd4d8
> README updated and credits polished.
>
> diff --git a/README b/README
> --- a/README
> +++ b/README
> @@ -64,7 +64,13 @@ 1. Documentation and usage
>
> Everything is at:
>
> -http://code.google.com/p/sympy/wiki/Documentation
> +http://docs.sympy.org/
> +
> +You can generate everything at the above site in your local copy of SymPy by:
> +
> +$ cd doc
> +$ make html
> +$ epiphany _build/html/index.html
good
>
> If you don't want to read that, here is a short usage:
>
> @@ -81,11 +87,11 @@ sympy namespace and executes some common
>
> To start it, issue:
>
> - ./bin/isympy
> +$ bin/isympy
I understand this works, but this is just a matter of style (and when
you type ./b<tab> bash autocompletes this to ./bin/ in contrast to
b<tab> where it does not, so I myself use ./bin/... , but again this is
just a matter of style, so I'm +0
>
> from this directory if SymPy is not installed or simply
>
> - isympy
> +$ isympy
ok
> if SymPy is installed somewhere in your PATH.
>
> @@ -158,7 +164,10 @@ A BibTeX entry for LaTeX users is::
> url = {http://www.sympy.org},
> }
>
> -We have invested a lot of time and effort in creating SymPy. Although not
> -required by SymPy license, if it is convenient for you, we ask to please cite
> -SymPy when using it in your work.
> -
> +SymPy is BSD licensed, so you are free to use it whatever you like, be it
> +academic, commercial, creating forks or derivatives, as long as you copy the BSD
> +statement if you redistribute it (see the LICENSE file for details).
> +That said, although not required by the SymPy license, if it is convenient for
> +you, please cite SymPy when using it in your work and also consider
> +contributing all your changes back, so that we can incorporate it and all of us
> +will benefit in the end.
I think this should be discussed more with team members, but at least it
would look clearier (for me), if you start new paragraph from "That said":
SymPy is BSD licensed, so you are free to use it whatever you like, be it
academic, commercial, creating forks or derivatives, as long as you copy the BSD
statement if you redistribute it (see the LICENSE file for details).
That said, although not required by the SymPy license, if it is convenient for
you, please cite SymPy when using it in your work and also consider
contributing all your changes back, so that we can incorporate it and all of us
will benefit in the end.
Although you know, I always was for LGPL (Library/Lesser GPL) in favour
of BSD...
Thanks for the patch and sorry for the delay in reviewing this.
--
Всего хорошего, Кирилл.
Kirill Smelkov
> # HG changeset patch
> # User Ondrej Certik <ond...@certik.cz>
> # Node ID 8edc6502a9759509795542f1fa50e0060d487660
> # Parent 04a669f38bb24e9afc7166a414d5b53327c8fb74
> Quick Start section added to the sympy-patches-tutorial.
Hmm, I think I'm ok with having something simplified just enough to
begin hacking, but having it first, even before introduction, seems to
me like diverting the whole tutorial idea:
you just hack forgetting about version control, and then you record
your patches, darcs style.
The patches done this way are pretty and structured and thus it is
good for everyone:
- it would be easier to review them,
- patches are more correct, because when you have to think of which
steps were done and writtenly describe it you'll sometimes catch
your own mistakes,
- and also it is easier for other team members to learn from your
experience after your code is merged, because when patches do one
thing and do it well (in contrast to "here is my next big new
improvement (which touches everything)" it is easier to learn for
others.
Maybe let's put this say into appendix, and link to it in the beginning
saying that just to get up and running, you could first use simpler (really ?)
more svn-like (?) approach.
What do you think?
>
> diff --git a/doc/src/sympy-patches-tutorial.txt b/doc/src/sympy-patches-tutorial.txt
> --- a/doc/src/sympy-patches-tutorial.txt
> +++ b/doc/src/sympy-patches-tutorial.txt
> @@ -18,6 +18,112 @@ SymPy Patches Tutorial
>
>
> .. role:: input(strong)
> +
> +Quick Start
> +===========
> +
> +This section explains how to get you up and running in 5 minutes. However we
> +recommend that you read the full tutorial below, at least the introduction and
> +then go briefly through the rest.
> +
> +Edit your :file:`~/.hgrc` (tell Mercurial your name and use git style diffs)::
btw, :file: role breaks spt-printable.html :
rst2html src/sympy-patches-tutorial.txt > _build/html/spt-printable.html
src/sympy-patches-tutorial.txt:29: (ERROR/3) Unknown interpreted text role "file".
src/sympy-patches-tutorial.txt:104: (ERROR/3) Unknown interpreted text role "file".
src/sympy-patches-tutorial.txt:107: (ERROR/3) Unknown interpreted text role "file".
> +
> + [ui]
> + username = Ondrej Certik <ond...@certik.cz>
> +
> + [diff]
> + git = true
> + showfunc = 1
> +
> +Download the latest SymPy hg and fix something:
> +
> +.. parsed-literal::
> +
> + $ :input:`hg clone http://hg.sympy.org/sympy`
> + destination directory: sympy
> + requesting all changes
> + adding changesets
> + adding manifests
> + adding file changes
> + added 2141 changesets with 7123 changes to 1065 files (+1 heads)
> + updating working directory
> + 416 files updated, 0 files merged, 0 files removed, 0 files unresolved
> + $ :input:`cd sympy`
> + $ :input:`vim sympy/matrices/matrices.py`
> +
> +Check your changes:
> +
> +.. parsed-literal::
> +
> + $ :input:`hg di`
> + diff --git a/sympy/matrices/matrices.py b/sympy/matrices/matrices.py
> + --- a/sympy/matrices/matrices.py
> + +++ b/sympy/matrices/matrices.py
> + @@ -23,7 +23,7 @@ class _MatrixAsBasic(Basic):
> + So for common functionality implemented in Basic, we have to provide this
> + proxy.
> +
> + - see #420
> + + see the issue #420
> + """
> + def __init__(self, m):
> + self.m = m
> +
> +Commit them:
> +
> +.. parsed-literal::
> +
> + $ :input:`hg ci -m "Matrix._MatrixAsBasic() docstring improved"`
> +
> +Check the final patch and save it to a file:
> +
> +.. parsed-literal::
> +
> + $ :input:`hg export tip`
> + # HG changeset patch
> + # User Ondrej Certik <ond...@certik.cz>
> + # Date 1213706432 -7200
> + # Node ID 9ad7000c53b914a4a196de87b67e0cd57a60a528
> + # Parent 2c92cefdd78ea34f070c97063802c92ef97fd4d8
> + Matrix._MatrixAsBasic() docstring improved
> +
> + diff --git a/sympy/matrices/matrices.py b/sympy/matrices/matrices.py
> + --- a/sympy/matrices/matrices.py
> + +++ b/sympy/matrices/matrices.py
> + @@ -23,7 +23,7 @@ class _MatrixAsBasic(Basic):
> + So for common functionality implemented in Basic, we have to provide this
> + proxy.
> +
> + - see #420
> + + see the issue #420
> + """
> + def __init__(self, m):
> + self.m = m
> + $ :input:`hg export tip > matrix.patch`
> +
> +and attach the file :file:`matrix.patch` to our issues_, or send it to our
> +list, preferably to the `sympy-...@googlecode.com`_ list.
> +
> +Tip: to send the patch to the sympy-patches list conveniently from the command
> +line, join the sympy-patches list with some email address and put this email
> +address together with these lines into your :file:`~/.hgrc`::
> +
> + [email]
> + to = sympy-...@googlegroups.com
> + from = Ondrej Certik <ond...@certik.cz>
> + method = /usr/sbin/sendmail
> +
> +and then:
> +
> +.. parsed-literal::
> +
> + $ :input:`hg email tip`
> + This patch series consists of 1 patches.
> +
> + Cc:
> +
> + Sending [PATCH] Matrix._MatrixAsBasic() docstring improved ...
> +
>
> Introduction
> ============
Thanks again for the patches, and sorry for the delay in reviewing this.
I wish I could finally get more than zero free time.
--
Всего хорошего, Кирилл.
Ondrej Certik
>>
>> - ./bin/isympy
>> +$ bin/isympy
>
> I understand this works, but this is just a matter of style (and when
> you type ./b<tab> bash autocompletes this to ./bin/ in contrast to
> b<tab> where it does not, so I myself use ./bin/... , but again this is
> just a matter of style, so I'm +0
Do I understand correctly that you are fine with either way?
I myself prefer the bin/isympy way, so I would push this in.
Agree, I'll bring this to our list first.
Ondrej
Kirill Smelkov
>
> >> To start it, issue:
> >>
> >> - ./bin/isympy
> >> +$ bin/isympy
> >
> > I understand this works, but this is just a matter of style (and when
> > you type ./b<tab> bash autocompletes this to ./bin/ in contrast to
> > b<tab> where it does not, so I myself use ./bin/... , but again this is
> > just a matter of style, so I'm +0
>
> Do I understand correctly that you are fine with either way?
Yes, +0 means exactly this.
> I myself prefer the bin/isympy way, so I would push this in.
Yes, please do it.
Thanks.
--
Всего хорошего, Кирилл.
Ondrej Certik
It's in.
Ondrej
Ondrej Certik
I did and noone has objected. Ok to go in?
Ondrej
Kirill Smelkov
I think it is.
--
Всего хорошего, Кирилл.