new astropy-style documentation about chiantipy HOT 25 CLOSED

Few quick hints:

build_sphinx is now an alias for build_docs I think astropy are deprecating the former.

python setup.py build_docs -O

will open the resulting build in your default web browser for you.

python setup.py build_docs -l 

will remove any old build artefacts.

from chiantipy.

To build the docs locally, run python setup.py build_sphinx. Then, assuming the ChiantiPy source is located in the directory $HOME, navigate to $HOME/ChiantiPy/docs/build/html/index.html in your web browser and you will be at the root of the documentation.

You should not need to create any extra directories and everything will be done inside the repo. The .gitignore includes a few lines to ignore all of the html produced by the Sphinx build since this is done on the RTD servers at every commit.

from chiantipy.

As an aside, if your build gets messed up somehow, you can clean everything out by deleting the directories $HOME/ChiantiPy/docs/build and $HOME/ChiantiPy/docs/source/api. These are both rebuilt when you run python setup.py build_sphinx.

from chiantipy.

both
> python3 setup.py build_sphinx
and
> python3 setup.py buld_docs

result in the following error:

Traceback (most recent call last):
File "", line 28, in
File "/usr/lib/python3.4/site-packages/sphinx/application.py", line 137, in init
confoverrides or {}, self.tags)
File "/usr/lib/python3.4/site-packages/sphinx/config.py", line 292, in init
execfile_(filename, config)
File "/usr/lib/python3.4/site-packages/sphinx/util/pycompat.py", line 130, in execfile_
exec_(code, _globals)
File "conf.py", line 111, in
import(setup_cfg['package_name'])
File "/data2/gh/ChiantiPy/build/lib.linux-x86_64-3.4/ChiantiPy/init.py", line 8, in
from ._astropy_init import *
File "/data2/gh/ChiantiPy/build/lib.linux-x86_64-3.4/ChiantiPy/_astropy_init.py", line 116, in
from astropy import config
ImportError: No module named 'astropy'

is there an easy way to get around installing 'astropy'?

from chiantipy.

It looks like you now have an astropy dependency in your ChiantiPy __init__.py file. I guess @wtbarnes did it?

So currently I think you need astropy.

from chiantipy.

Yes ChiantiPy/__init__.py makes the call from ._astropy_init.py import * which depends on astropy.

from chiantipy.

as we are very early into the process of making ChiantiPy into an acceptable AstroPy package, I would prefer not to make it a dependency just yet. I have found that by modify in the /ChiantiPy/init.py to include just the following code:

__version__ = '0.7.0'

I have just commented out the parts the import _astropy_init

doing this, I am able to build the docs locally. As the changes are only to init.py, it is easy to go back.

from chiantipy.

I can understand not wanting to add another dependency, especially given that such a small portion of ChiantiPy depends on it at the moment.

However, given that Python dependencies are so easily installed (e.g. pip or conda) and requires little effort on the part of the user, I don't really see the harm in adding an extra dependency. Also, most of the heavy "dependency baggage" that Astropy carries with it (e.g. scipy, numpy, matplotlib) is already included in the ChiantiPy dependencies.

If you'd still like to proceed without astropy as a dependency, I would recommend just commenting out from ._astropy_init.py import * (as you did) and then pasting in

try:
    from .version import version as __version__
except ImportError:
    __version__ = ''
try:
    from .version import githash as __githash__
except ImportError:
    __githash__ = ''

so that we still avoid hardcoding the version number in the code itself. I believe this is what SunPy has done as well.

EDIT: You'll also need to comment out the if not _ASTROPY_SETUP_: statement as this variable is defined in _astropy_init.py.

from chiantipy.

I have come to the conclusion that the astropy documentation structure is not a good fit for the ChiantiPy documentation.
The astropy style allows for keywords such as parameters, returns,attributes. For ChiantiPy, the only things that uses need to access are the classes ion, bunch, and the spectrum classes. These never return anything. What they do provide are a lot ofattributesthat are created by varioustools`. Attributes do not document well. They are allotted a single line with a horizontal scroll bar. Most Attributes are dicts with a reasonable number of keys that each need to be documented. In addition, although it is perhaps minor, I would like to be able to list Arguments and Keyword-Arguments separately.

The Astropy docs (somewhere) state that to be an affiliated package, they would like you to use the Astropy doc package but they will accept something as long as it is well documented. I peeked at some of the Astropy documentation and some of it give a large amount of details, including examples. A lot of it also just has single line doc strings so I am not sure just how high their standards are.

My proposal is to go to a pure sphinx-rst doc style. This is what I used before but I did not understand how to do the api documentation except with external programs like `Epydoc'. I am looking into that now. I would like to get away from importing a lot of Astropy stuff that is not make a lot of initial sense to me.

Comments are definitely welcome.

from chiantipy.

I see your point in that the Attributes section is not really given the same deference as say Methods in the class docstring. However, it is worth noting that the one-line/scroll bar display is just the preview at the top of the class definition. From what I can tell, clicking on the variable name links to an extended description below. See, e.g. the SunPy TimeRange class.

The differentiation between arguments and keyword arguments is usually just by adding an optional tag to the variable description in parameters. Note also that in the function signature for a method or function, keyword arguments are automatically denoted by wrapping the argument in square brackets or by arg=DefaultValue.

Regarding Astropy affiliation, I think it might be more worthwhile to consider @Cadair's suggestion of becoming a SunPy-affiliated package given that CHIANTI/ChiantiPy are most popular with the solar physics community.

My initial motivation for using astropy-helpers to build the documentation was actually because (and this is my very much my naive opinion!) vanilla sphinx is really lacking in its ability to automatically build API documentation. In particular, I found it very difficult to automatically generate the API docs for every git commit on Read the Docs. I think this is very essential in keeping the ChiantiPy docs current.

Somewhat more trivially, astropy-helpers also provides some nice features like inter-linking between NumPy, SciPy, and matplotlib documentation so that you can just click variable type, e.g. numpy.ndarray and it will link you to the NumPy doc page for ndarray. This could be especially important to those not familiar with the scientific Python ecosystem, e.g. solar physicists primarily familiar with IDL.

@Cadair and @ehsteve probably have far more insight into the pros/cons of astropy-helpers and maybe can address some of the shortcomings that you raise here.

from chiantipy.

I have been looking into using native sphinx for API documentation and it does look like it is fairly brittle , once you figure it out.
OK, so let's keep going as we are and see how we can adapt.
As for SunPY, what would we be doing differently? It is true that most CHIANTI users are from solar physics.
While I remember it, the doc strings for the _IonTrails and _SpecTrails modules are displayed. I suspect there is some kind of ignore in the AstroPy setup for sphinx. This needs to be solved but not right now.
Again, if someone out there has a comment, they are welcome to express it.

from chiantipy.

Regarding SunPy affiliation, @Cadair posted this link in #11. This basically just boils down to having well-maintained and thorough documentation and a test suite. The requirements are pretty loosely defined. Having SunPy affiliation may help ChiantiPy gain more popularity as well, both in a user and developer sense.

I see your point about classes like _IonTrails and _SpecTrails. These are not important to the typical user so they shouldn't be as "user-facing" in the docs as objects like ion, continuum, etc. However, I just noticed that they don't seem to appear on the core docs page...

On the other hand, the docs are also important to those who might want to contribute to ChiantiPy so I think it is still important to expose the documentation for parts of the code that are not useful to the typical user.

One strategy might be to separate out _IonTrails.py, _SpecTrails.py (and any other base/non-user-facing classes) into a new module, e.g. ChiantiPy/base. Then all of the core classes just import these from ChiantiPy/base. In this way, both the documentation and the code can be separated so that it is clear to both users and developers how/when these pieces of code should be used.

from chiantipy.

I am happy to go with SunPy.
As for _IonTrails and _Spectrails, these are pseudo-classes (there probably is a more official name for them) but they have important methods that are inherited by the ion, bunch and spectrum classes that are useful to users. We could just rename the files to IonTrails.py and SpecTrails.py if it makes the documentation easier. I just did not want users to think that these were classes that they might want to instantiate.

from chiantipy.

Great! I'll bring this up in the SunPy community meeting on Wednesday.

Regarding the IonTrails.py and SpecTrails.py, it actually sounds like putting them in a new location (e.g. ChiantiPy/base) would be the best option. That way, they can be removed from the ChiantiPy/core documentation, but they can still have their own separate documentation page (currently they have no page on RTD because they are not imported directly by ChiantiPy/core).

This way, typical users won't be distracted by docs that are not important to everyday ChiantiPy use and contributors/developers still have easy access to the docs for these base classes.

from chiantipy.

I have been experimenting with Sphinx autodoc and its various commands, using an older version of ChiantiPy. It will pull in the documentation for inherited methods with
:inherited-methods:
and that seems to work fine. Otherwise, I seem to be reverse engineering a documentation setup that is not well documented.

from chiantipy.

I have put the new Sphinx docs for version online
here
I would prefer to go this way as we have control, within the limitations of Sphinx and rst, over the documentation

from chiantipy.

Certainly a vanilla Sphinx approach gives way more control over how the docs are built. However, I'm confused as to what advantage we gain with this approach... The attributes for Ion, Continuum, and Spectrum still don't seem to be documented here?

Additionally, would you prefer to continue bundling the docs with the source code on GitHub and publishing with RTD or hosting the docs on a separate server?

While I agree there are some "black box" parts to astropy-helpers, I think it offers a lot in the way of useful boilerplate. This includes things like cross-linking with other documentation (e.g. NumPy), links back to the source code on GitHub, cross-referencing with other modules within the same package, etc.

It's also worth noting that the sphinx doc style is very flexible (even with the extra order imposed by astropy-helpers) in that the API TOC does not need to be structured the way it currently is and could be reorganized very easily. For example, I've imposed (by hand) what goes into the ChiantiPy/tools page on the API docs and in what order (see here). So if we wanted emphasize the docs for the user-facing modules (e.g. Ion, Continuum, Spectrum) over ones not so important to typical users (e.g. _IonTrails.py or ChiantiPy/tools), this is in principle just a matter of shuffling around the TOC (and maybe some import statements).

from chiantipy.

sorry, I did not say that the docs were for an older version - that is why you don't see a lot of things.. I will try to put some vanilla docs up tomorrow for the latest version.
RTD is fine by me as long as we can get it working.
About the only numpy things that we document are arrays so that is not so important but we can still use the sphinx extension numpydoc.
_IonTrails and _SpecTrails are important because they contain methods that are inherited and important to the user.
So far I have not changed anything in my git repository so I would like to experiment around a bit more.

from chiantipy.

after experimenting around with the native Sphinx commands, I have gone back to using the astropy/numpy Sphinx setup we started out with.

from chiantipy.

My experience with vanilla Sphinx a few months ago was very similar. I did the initial docs build for ChiantiPy without any boilerplate and it worked Ok, but the results weren't very clean and building the API docs automatically was very cumbersome.

It is not always clear to me what is going on in the astropy-helpers boilerplate, but it is the best solution I've come across thus far. It also seems to be well supported by the astropy team so any issues we come across will most likely be resolved quickly.

from chiantipy.

I have just updated ipymspectrum as it had stopped working and rewrote the quickstart notebook.

I would like to finish up the documentation and get out a new release.

Right now, the way the documentation is set up, it ignores all files that start with and underscore, such as _SpecTrails.py. I think the only way to get around this is to rename the files just SpecTrails.py and change the various import statements.

So, I am planning to do that soon

from chiantipy.

By ignored, do you mean not listed in the API documentation? If so, the reason for this is not because they have an underscore in front of their name, but because they are not imported in ChiantiPy/core/__init__.py.

from chiantipy.

OK, I will give that a try

from chiantipy.

I think this issue can be closed.

from chiantipy.

OK

from chiantipy.