Hi,
I have written some notes summarizing how to contribute to our project, see [1]. Updates to the text from other sides are welcome!
r.
[1] http://docs.sfepy.org/doc-devel/developer_guide.html
Thanks Robert -
Reading through the guide I missed a writeup on contributing to the documentation side of the project. From what I've been able to gather from the source, the documents are in restructured text format and uses Sphinx, docutils, etc which is all new to me. I would like to at least review any changes I make before submitting changes or updates - but I'm guessing that this needs the documentation posted to a server that runs Sphinx? Any suggestions?
I found some editors: http://code.google.com/p/crunchy/ http://catherinedevlin.blogspot.com/2009/08/enthoughts-restructuredtext-edit...
Andre
On 04/26/10 14:43, Andre Smit wrote:
Thanks Robert -
Reading through the guide I missed a writeup on contributing to the documentation side of the project. From what I've been able to gather from the source, the documents are in restructured text format and uses Sphinx, docutils, etc which is all new to me. I would like to at least review any changes I make before submitting changes or updates - but I'm guessing that this needs the documentation posted to a server that runs Sphinx? Any suggestions?
Ah, ok, this is easy, you can review the results on your computer:
- install sphinx + numpydoc [0], set the path to numpydoc in site_cfg.py if
needed.
- edit the rst files in doc/ using any text editor (I use emacs) - the ReST
format is really simple, so nothing fancy is needed. Follow the existing files in doc/, for reference check also [1-3].
- (re)generate the documentation (assuming linux, for windows I could add a
.bat file instead of Makefile, if needed)
cd doc make html
- view it
firefox _build/html/index.html # use your favorite browser
I found some editors: http://code.google.com/p/crunchy/ http://catherinedevlin.blogspot.com/2009/08/enthoughts-restructuredtext-edit...
Thanks for the links, but I guess your usual text editor (that you edit Python sources with) should do too.
cheers, r.
[0] http://pypi.python.org/pypi/numpydoc/0.3.1 [1] http://sphinx.pocoo.org/rest.html [2] http://sphinx.pocoo.org/markup/index.html [3] http://docutils.sourceforge.net/rst.html
On 04/26/10 14:57, Robert Cimrman wrote:
On 04/26/10 14:43, Andre Smit wrote:
Thanks Robert -
Reading through the guide I missed a writeup on contributing to the documentation side of the project. From what I've been able to gather from the source, the documents are in restructured text format and uses Sphinx, docutils, etc which is all new to me. I would like to at least review any changes I make before submitting changes or updates - but I'm guessing that this needs the documentation posted to a server that runs Sphinx? Any suggestions?
Ah, ok, this is easy, you can review the results on your computer:
- install sphinx + numpydoc [0], set the path to numpydoc in
site_cfg.py if needed.
- edit the rst files in doc/ using any text editor (I use emacs) - the
ReST format is really simple, so nothing fancy is needed. Follow the existing files in doc/, for reference check also [1-3].
- (re)generate the documentation (assuming linux, for windows I could
add a .bat file instead of Makefile, if needed)
cd doc make html
- view it
firefox _build/html/index.html # use your favorite browser
I found some editors: http://code.google.com/p/crunchy/ http://catherinedevlin.blogspot.com/2009/08/enthoughts-restructuredtext-edit...
Thanks for the links, but I guess your usual text editor (that you edit Python sources with) should do too.
cheers, r.
[0] http://pypi.python.org/pypi/numpydoc/0.3.1 [1] http://sphinx.pocoo.org/rest.html [2] http://sphinx.pocoo.org/markup/index.html [3] http://docutils.sourceforge.net/rst.html
This is now at [4].
[4] http://docs.sfepy.org/doc-devel/developer_guide.html#how-to-regenerate-docum...
r.
I'm confused, my natural state of mind :)
In the Developer Guide, Section "Contributing changes" you indicate:
- Send the patches like described in the previous Section.
This is unclear - the previous section (Making changes?) doesn't discuss patches. Also - why generate patches if the commits already reflect changes?
Hi Andre,
On Mon, Apr 26, 2010 at 1:51 PM, Andre Smit freev...@gmail.com wrote:
I'm confused, my natural state of mind :)
Mine too ;)
In the Developer Guide, Section "Contributing changes" you indicate:
- Send the patches like described in the previous Section.
This is unclear - the previous section (Making changes?) doesn't discuss patches. Also - why generate patches if the commits already reflect changes?
I guess Robert meant the "Without git" section, i.e., attach the patches to this mailing list or the issue tracker on google code. Probably it would be more clear IMHO to repeat this information on step 5.
For the second question, I guess generating patches are just one way. The other way would be to publish your git repository on, e.g., github. Then you can setup your local git copy to push your commits to github and then Robert can pull them into the main sfepy repository.
HTH! Keep asking questions! Also, feel free to edit and clarify and add to the documentation...it needs a lot of work yet. Btw, I really like your beginner's tutorial on the google wiki page. Perhaps we can incorporate it into the rst documentation?
Logan
Thanks Logan - that helps.
Regarding the wiki primer, thanks for your comments. I need another week or so to wrap up the draft. I like the flexibility of the google wiki format i.e. editing on the fly, easy http linking, etc. Still learning so I haven't been able to really format the document as I want. I've been dumping images into http://groups.google.com/group/sfepy-devel/files?hl=en, which will probably get messy without a directory structure. In the interim though I'm hoping the group will go over and refine the rough draft - and I think the google wiki page is best for that.
Andre
On Mon, Apr 26, 2010 at 1:19 PM, Logan Sorenson logan.s...@gmail.comwrote:
Hi Andre,
On Mon, Apr 26, 2010 at 1:51 PM, Andre Smit freev...@gmail.com wrote:
I'm confused, my natural state of mind :)
Mine too ;)
In the Developer Guide, Section "Contributing changes" you indicate:
- Send the patches like described in the previous Section.
This is unclear - the previous section (Making changes?) doesn't discuss patches. Also - why generate patches if the commits already reflect
changes?
I guess Robert meant the "Without git" section, i.e., attach the patches to this mailing list or the issue tracker on google code. Probably it would be more clear IMHO to repeat this information on step 5.
For the second question, I guess generating patches are just one way. The other way would be to publish your git repository on, e.g., github. Then you can setup your local git copy to push your commits to github and then Robert can pull them into the main sfepy repository.
HTH! Keep asking questions! Also, feel free to edit and clarify and add to the documentation...it needs a lot of work yet. Btw, I really like your beginner's tutorial on the google wiki page. Perhaps we can incorporate it into the rst documentation?
Logan
-- You received this message because you are subscribed to the Google Groups "sfepy-devel" group. To post to this group, send email to sfepy...@googlegroups.com. To unsubscribe from this group, send email to sfepy-devel...@googlegroups.comsfepy-devel%...@googlegroups.com . For more options, visit this group at http://groups.google.com/group/sfepy-devel?hl=en.
Hey Andre,
On Mon, Apr 26, 2010 at 3:45 PM, Andre Smit freev...@gmail.com wrote:
Thanks Logan - that helps.
Regarding the wiki primer, thanks for your comments. I need another week or so to wrap up the draft. I like the flexibility of the google wiki format i.e. editing on the fly, easy http linking, etc. Still learning so I haven't been able to really format the document as I want. I've been dumping images into http://groups.google.com/group/sfepy-devel/files?hl=en, which will probably get messy without a directory structure. In the interim though I'm hoping the group will go over and refine the rough draft - and I think the google wiki page is best for that.
No problem! We can keep it on the wiki for now as it is being crafted. :)
Logan
On 04/26/10 23:30, Logan Sorenson wrote:
Hey Andre,
On Mon, Apr 26, 2010 at 3:45 PM, Andre Smitfreev...@gmail.com wrote:
Thanks Logan - that helps.
Regarding the wiki primer, thanks for your comments. I need another week or so to wrap up the draft. I like the flexibility of the google wiki format i.e. editing on the fly, easy http linking, etc. Still learning so I haven't been able to really format the document as I want. I've been dumping images into http://groups.google.com/group/sfepy-devel/files?hl=en, which will probably get messy without a directory structure. In the interim though I'm hoping the group will go over and refine the rough draft - and I think the google wiki page is best for that.
No problem! We can keep it on the wiki for now as it is being crafted. :)
Oh yes, the wiki is perfect for "collaborative writing". The sphinx docs are more for a "finished texts"-like stuff. Ideally. Well. Most of the time it should be so.
Transforming the resulting text to a sphinx compatible form should not be difficult, after all.
Thanks for working on the primer!
r.
On 04/26/10 21:45, Andre Smit wrote:
Thanks Logan - that helps.
Regarding the wiki primer, thanks for your comments. I need another week or so to wrap up the draft. I like the flexibility of the google wiki format i.e. editing on the fly, easy http linking, etc. Still learning so I haven't been able to really format the document as I want. I've been dumping images into http://groups.google.com/group/sfepy-devel/files?hl=en, which will probably get messy without a directory structure. In the interim though I'm hoping the group will go over and refine the rough draft - and I think the google wiki page is best for that.
There is an alternative way of getting your files to the site, that you might be unaware of. The original source tab [1] contains instructions how to download the sources (plug there your google account name instead of mine, use the generated password according to instructions):
svn checkout https://sfepy.googlecode.com/svn/trunk/ sfepy --username robert.cimrman
which does nothing :), since we use git - but a little modification (remove the 'trunk'):
svn checkout https://sfepy.googlecode.com/svn sfepy-site --username robert.cimrman
downloads the whole site contents including the wiki pages, the attachments etc.
Now you can add/modify/delete files in there, and when you are satisfied, just use
svn add <some files> svn commit -m 'some message'
to update the web site.
For example, the images used in the Examples wiki page are under sfepy/web/, so you could put your images in a subdirectory there too.
cheers, r.
[1] http://code.google.com/p/sfepy/source/checkout
On 04/26/10 20:19, Logan Sorenson wrote:
Hi Andre,
On Mon, Apr 26, 2010 at 1:51 PM, Andre Smitfreev...@gmail.com wrote:
I'm confused, my natural state of mind :)
Mine too ;)
Heh, welcome on board! :)
In the Developer Guide, Section "Contributing changes" you indicate:
- Send the patches like described in the previous Section.
This is unclear - the previous section (Making changes?) doesn't discuss patches. Also - why generate patches if the commits already reflect changes?
I guess Robert meant the "Without git" section, i.e., attach the patches to this mailing list or the issue tracker on google code. Probably it would be more clear IMHO to repeat this information on step 5.
Yes, I meant the "Without git" section, but repeating it would not hurt. I will fix it.
For the second question, I guess generating patches are just one way. The other way would be to publish your git repository on, e.g., github. Then you can setup your local git copy to push your commits to github and then Robert can pull them into the main sfepy repository.
Exactly. The commits reflect changes, but only in your _local_ git repository. Then you must somehow allow others to see them and me to integrate them into the main repository. This can be done either by sending a patch here, by attaching it to an issue, or via github. For small things I slightly prefer sending the patches - github is necessary in case of a longer parallel development that would involve non-fast-forward merging and stuff like that. On the other hand, setting a personal github repo is a good idea - it's a good backup.
BTW. a patch can be easily applied:
git am < 0001_my_cool_patch
HTH! Keep asking questions! Also, feel free to edit and clarify and add to the documentation...it needs a lot of work yet. Btw, I really like your beginner's tutorial on the google wiki page. Perhaps we can incorporate it into the rst documentation?
+1, very nice.
r.
On 04/27/10 10:06, Robert Cimrman wrote:
On 04/26/10 20:19, Logan Sorenson wrote:
Hi Andre,
On Mon, Apr 26, 2010 at 1:51 PM, Andre Smitfreev...@gmail.com wrote:
I'm confused, my natural state of mind :)
Mine too ;)
Heh, welcome on board! :)
In the Developer Guide, Section "Contributing changes" you indicate:
- Send the patches like described in the previous Section.
This is unclear - the previous section (Making changes?) doesn't discuss patches. Also - why generate patches if the commits already reflect changes?
I guess Robert meant the "Without git" section, i.e., attach the patches to this mailing list or the issue tracker on google code. Probably it would be more clear IMHO to repeat this information on step 5.
Yes, I meant the "Without git" section, but repeating it would not hurt. I will fix it.
For the second question, I guess generating patches are just one way. The other way would be to publish your git repository on, e.g., github. Then you can setup your local git copy to push your commits to github and then Robert can pull them into the main sfepy repository.
Exactly. The commits reflect changes, but only in your _local_ git repository. Then you must somehow allow others to see them and me to integrate them into the main repository. This can be done either by sending a patch here, by attaching it to an issue, or via github. For small things I slightly prefer sending the patches - github is necessary in case of a longer parallel development that would involve non-fast-forward merging and stuff like that. On the other hand, setting a personal github repo is a good idea - it's a good backup.
I have updated the docs to include the above information. Let me know if all is clear now.
thanks, r.
I followed the instructions to install sphinx and numpydoc. During the make html I got the following errors (truncated):
/home/grassy/sfepy_dev/sfepy/sfepy/terms/terms_hyperelastic_ul.py:docstring of sfepy.terms.terms_hyperelastic_ul.NeoHookeanULTerm:4: (WARNING/2) Field list ends without a blank line; unexpected unindent. /home/grassy/sfepy_dev/sfepy/sfepy/terms/terms_hyperelastic_ul.py:docstring of sfepy.terms.terms_hyperelastic_ul.NeoHookeanULTerm:8: (WARNING/2) Field list ends without a blank line; unexpected unindent. looking for now-outdated files... none found pickling environment... done checking consistency... /home/grassy/sfepy_dev/sfepy/doc/term_table.rst:: WARNING: document isn't included in any toctree done preparing documents... done WARNING: LaTeX command 'latex' cannot be run (needed for math display), check the pngmath_latex setting writing output... [100%] users_guide yperelastic_ulses writing additional files... genindex modindex search copying images... images/sfepy_gui.png images/elements.png images/postproc_simple.png copying static files... WARNING: static directory '/home/grassy/sfepy_dev/sfepy/doc/_static' does not exist done dumping search index... done dumping object inventory... done build succeeded, 288 warnings.
I guess the one that stands out is that latex is also needed for equations.
A
participants (3)
-
Andre Smit -
Logan Sorenson -
Robert Cimrman