documentation, sound and music [was: doc? music through mathematical relations between LPCM samples and musical elements/characteristics]
Dear Scipy-ers, If you think I should split the message so that things get more clear... But the things are: 1) How to document numpy-heavy projects? 2) How to better make these contributions available to the numpy/scipy community? Directions will be greatly appreciated. I suspect that this info is all gathered somewhere I did not find. PS. I apologize for the cross-post, this is a message sent to numpy list but without any replies, so I found fit to send the message to both lists. Thanks in advance, Best, R. ---------- Forwarded message ---------- From: Renato Fabbri <renato.fabbri@gmail.com> Date: Tue, Jan 30, 2018 at 8:32 PM Subject: doc? music through mathematical relations between LPCM samples and musical elements/characteristics To: Discussion of Numerical Python <numpy-discussion@python.org> the half-shape suite: archive.org/details/ShapeSuite was completely synthesized using psychophysical relations for each resulting 16bit 44kHz samples: https://arxiv.org/abs/1412.6853 I am thinking about the ways in which to make the documentation at least to: * mass (music and audio in sample sequences): the framework. It might be considered a toolbox, but it is not a package: https://github.com/ttm/mass/ * music: a package for making music, including the routines used to make the half-shape suite: https://github.com/ttm/music == It seems reasonable at first to: * upload the package to PyPI (mass is not a package), music is there (beta but there). * Make available some summary of the file tree, including some automated code documentation. As I follow numpy's convention (or try to), and the package and framework are particularly useful for proficient numpy users, I used Sphinx. The very preliminary version is: https://pythonmusic.github.io/ * Make a nice readthedocs documentation. "music" project name was taken so I made: http://music-documentation.readthedocs.io/en/latest/ "mass" project name was also taken so I made: http://musicmass.readthedocs.io/en/latest/ And I found these URLs clumsy. Is there a standard or would you go with musicpackage.read.. and massframework.read... ? More importantly: * would you use readthedocs for the sphinx/doxigen output? * would you use readthedocs.org or a gitbook would be better or...? Should I contact the scipy community to make available a scikit or integrate it to numpy in any way beyond using and citing it appropriately?. BTW. I am using vimwiki with some constant attempt to organize and track my I/O: https://arxiv.org/abs/1712.06933 So maybe a unified solution for all these documentation instances using a wiki structure seems reasonable at the moment. Maybe upload the generated html from Sphinx and from Vimwiki to readthedocs...? Best, R. -- Renato Fabbri GNU/Linux User #479299 labmacambira.sourceforge.net -- Renato Fabbri GNU/Linux User #479299 labmacambira.sourceforge.net
On Thu, Feb 1, 2018 at 7:38 AM, Renato Fabbri <renato.fabbri@gmail.com> wrote:
Dear Scipy-ers,
If you think I should split the message so that things get more clear...
But the things are: 1) How to document numpy-heavy projects?
There is nothing particularly special about numpy-heavy projects with respect to documentation. The tools used for numpy and scipy's documentation may (or may not) be useful to you. For example, you may want to embed matplotlib plots into your documentation. https://pypi.python.org/pypi/numpydoc But if not, don't worry about it. Sphinx is all most numpy-heavy projects need, like most Python projects. Hosting the documentation on either readthedocs or Github is fine. Do whatever's convenient for you. Either is just as convenient for us.
2) How to better make these contributions available to the numpy/scipy community?
Having it up on Github and PyPI is all you need to do. Participate in relevant mailing list conversations. While we don't forbid release announcement emails on either of the lists, I wouldn't do much more than announce the initial release and maybe a really major update (i.e. not for every bugfix release).
Directions will be greatly appreciated. I suspect that this info is all gathered somewhere I did not find.
Sorry this isn't gathered anywhere, but truly, the answer is "there is not much to it". You're doing everything right. :-) -- Robert Kern
I think you gave me the answers: 0) It seems reasonable to just use sphinx, no jekyll or anything more, only if a need for it is found. I might use some HTML generated by vimwiki for pure convenience. 1) Make the main documentation with sphinx. That means joining: <githubio sphinx music> and <readthedocs music> 2) github.io, gitbook, readthedocs, all is just as fine. Maybe github.io makes it easier and has more features, while readthedocs is maybe more traditional for these kinds of python-related docs. 3) just realese on pypi, make the documentation fine and tell the list. If any major release deserves a message, it is ok to send. 3.1) A scikit to make psychoacoutic experiments, synthesize audio and music, is not absurd nor deeply compelling. 4) Am I loosing something? Being mindful of this question is always good, but that is it, we are on track. (the python and latex files are on github, so there is an issue tracker, a wiki etc etc there if anything comes up) tx++ On Wed, Jan 31, 2018 at 9:20 PM, Robert Kern <robert.kern@gmail.com> wrote:
On Thu, Feb 1, 2018 at 7:38 AM, Renato Fabbri <renato.fabbri@gmail.com> wrote:
Dear Scipy-ers,
If you think I should split the message so that things get more clear...
But the things are: 1) How to document numpy-heavy projects?
There is nothing particularly special about numpy-heavy projects with respect to documentation. The tools used for numpy and scipy's documentation may (or may not) be useful to you. For example, you may want to embed matplotlib plots into your documentation.
https://pypi.python.org/pypi/numpydoc
But if not, don't worry about it. Sphinx is all most numpy-heavy projects need, like most Python projects. Hosting the documentation on either readthedocs or Github is fine. Do whatever's convenient for you. Either is just as convenient for us.
2) How to better make these contributions available to the numpy/scipy community?
Having it up on Github and PyPI is all you need to do. Participate in relevant mailing list conversations. While we don't forbid release announcement emails on either of the lists, I wouldn't do much more than announce the initial release and maybe a really major update (i.e. not for every bugfix release).
Directions will be greatly appreciated. I suspect that this info is all gathered somewhere I did not find.
Sorry this isn't gathered anywhere, but truly, the answer is "there is not much to it". You're doing everything right. :-)
-- Robert Kern
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
-- Renato Fabbri GNU/Linux User #479299 labmacambira.sourceforge.net
participants (2)
-
Renato Fabbri -
Robert Kern