artview
artview copied to clipboard
nguy
Documentation
Just as a starting comment, I think pyart documentation is really good, if we could do something similar would be nice
I like PyArt documentation as well, but more importantly keeping a similar structure is probably the right way to go given that ARTView is essentially an extension of PyArt.
@gamaanderson - looking into this now. Been super busy with our field project deployment the last few weeks.
In README::USAGE there is no .py in the following:
python artview.py -d /some/directory/you/want/to/point/to
there is no longer a artview.py file
I realized I hit the wrong button, we can keep this open as we move forward with Documentation.
@tjlang just a heads up!
I just realized that pep8 complained about #: and changed to # :, however I do need this to document attributes according with sphynx autodoc. There is no need to correct that now, I will make the changes in my fork and this will come back in some PR.
It would be nice to see if you can rebuild the documentation, but it may be not that easy, I had to fight a lot to get it running.
first you will need to install Sphinx
then run rebuild_docs.sh (in folder docs/)
if you do built it successfully, use git status to check for new files in docs/build/html, you need to add those files to git.
I tested, and got 23 Warning, normally I get 3, those are the following, I understand them and they are ok.
checking consistency...
/home/gama/artview/docs/source/auto_examples/index.rst:: WARNING: document isn't included in any toctree
/home/gama/artview/docs/source/reference/generated/artview.core.core.Component.rst:: WARNING: document isn't included in any toctree
/home/gama/artview/docs/source/reference/generated/artview.core.core.Variable.rst:: WARNING: document isn't included in any toctree
done
the other 20 warning should be addressed, if you have problems with changes not taking place remove all files from folder docs/source/reference/generated/ (add rm source/reference/generated/* to rebuild_docs.sh if you want)
In any case, I'm here for help. Also remember I'm running everything in Debian, and I don't know if this will work in MacOSX
also, before all that, you may need to build/install artview to get the right version number in the documentation (one gets the version from the automatically created artview/version.py not setup.py).
I updated the version number in setup.py, if I'm not mistaken this is the only place the update needs to be applied and then the new version.py is created by build/install.
Okay as for the documentation, I also get the 23 warnings after running rebuild_docs.sh. Now can you help me understand what needs to be changed? Do I need to modify the .rst files where the warnings were thrown?
most of those warning is because artview.components.Display changed to artview.components.RadarDisplay. You can start going after this in the doc-strings and see how many warnings are left
the only .rst files you need to see, are the tutorials: docs/source/script_tutorial.rst docs/source/plugin_tutorial.rst those also need actualization, including the code examples
Okay, I have the warnings down to 15. I pushed the update.
Many still the same as you note above (I fixed multiple instances), but I can't find any instances with a grep command.
Also, what is toctree?
toctree is how sphinx organize the links, or something like that.
/home/gama/artview/docs/source/reference/components.rst:14: WARNING: failed to import Display
/home/gama/artview/docs/source/reference/components.rst:14: WARNING: failed to import TiltButtonWindow
/home/gama/artview/docs/source/reference/components.rst:14: WARNING: toctree references unknown document u'reference/generated/Display'
/home/gama/artview/docs/source/reference/components.rst:14: WARNING: toctree references unknown document u'reference/generated/TiltButtonWindow'
in components/__init__.py one need to actualize the initial doc string, to remove Display and TiltButtonWindow and add RadarDisplay, GridDisplay and LevelButtonWindow
I have no real experience in it but I have made a video, for now it is unlisted, so only we can see it. It has no sound, since I do not trust my voice, but it has some sub-titles. @nguy, @tjlang, @swnesbitt it has your names in the end, so make sure you all agree with it, also please revise the English.
If someone wants to improve it or add sound, the mp4 and the subtitle srt are here. I may also provide the original recordings (12min+) if needed.
Version 1.3 is getting closer, so we will need to review the docs. Also new tutorial are important. I know my voice is not the best so it would be really nice if someone would do the tutorial. It is certainly a lot of work and would be perfect for some one that want to help but don't want or don't know how to get in the code. I would certainly add such a person as author in the presentation at the AMS conference.
Good idea. I'll try to do some as well. I'll try to go through the code and update docstrings, etc. before doing a doc build as a final bit before release.