Skip to content

Add starting point for documentation - #158

Merged
xylar merged 12 commits into
MPAS-Dev:developfrom
xylar:sphinx_support
Sep 19, 2017
Merged

Add starting point for documentation#158
xylar merged 12 commits into
MPAS-Dev:developfrom
xylar:sphinx_support

Conversation

@xylar

@xylar xylar commented Mar 25, 2017

Copy link
Copy Markdown
Collaborator

Add support for creating documentation using sphinx.

So far, only basic, autogenerated documentation of the API for all public module functions (except CI tests) is included.

Docstrings for run_analysis.py, generalized_reader and mpas_xarray have been updated to produce better formatting in autodocs. In the future, all docstrings would need to be carefully checked and fixed as needed.

@xylar

xylar commented Mar 25, 2017

Copy link
Copy Markdown
Collaborator Author

To try it out:

conda install sphinx sphinx_rtd_theme numpydoc
cd docs
make html

Then, open _build/html/index.html in your browser to see the results.

@xylar

xylar commented Mar 25, 2017

Copy link
Copy Markdown
Collaborator Author

Eventually, we will want to use Read the Docs to host our documentation and update it automatically from the repo. This is what xarray does. For now, we'll just work on making it useful.

@xylar
xylar force-pushed the sphinx_support branch 2 times, most recently from d0cc562 to e59cc76 Compare March 25, 2017 15:48
@xylar

xylar commented Mar 25, 2017

Copy link
Copy Markdown
Collaborator Author

Once we have this up and running, a requirement of each PR should be making sure the appropriate documentation is in place. For now, this may just be a question of adding any new classes and functions to api.rst so the documentation gets autogenerated from the docstring. Later on, we'll want to add more thorough documentation with examples and more details.

@xylar

xylar commented Mar 25, 2017

Copy link
Copy Markdown
Collaborator Author

This is meant to address #3 (at least to the point where we can close the issue -- documenting the code will be an ongoing effort).

@xylar
xylar force-pushed the sphinx_support branch 2 times, most recently from 82b27b2 to 2acb352 Compare March 26, 2017 12:52
@xylar xylar assigned xylar and unassigned pwolfram Sep 9, 2017
@xylar

xylar commented Sep 9, 2017

Copy link
Copy Markdown
Collaborator Author

@pwolfram and @milenaveneziani, I'd like to push ahead with the documentation. I just updated the work I had done back in March and a lot has changed since then so there was quite a bit of clean up to do just to get things back to how they were back then. I think if we were making sure there was at least minimal documentation as we go, it would make things much easier.

@pwolfram, I know you haven't been very involved in MPAS-Analysis lately. Let me know if you're interested in reviewing this PR. I'd definitely appreciate your feedback. Otherwise, feel free to take yourself off as a reviewer.

@xylar

xylar commented Sep 9, 2017

Copy link
Copy Markdown
Collaborator Author

The current documentation as generated by sphinx can be found here:
http://portal.nersc.gov/project/m2833/xylar/mpas_analysis/docs/

Obviously, this is just a temporary location for convenience until we get things to a point that we're ready to put them up on some more permanent portal.

@xylar

xylar commented Sep 9, 2017

Copy link
Copy Markdown
Collaborator Author

@vanroekel, your feedback would also be welcome.

@xylar

xylar commented Sep 10, 2017

Copy link
Copy Markdown
Collaborator Author

@jhkennedy, I'd appreciate any suggestions you might have on our baby steps toward documentation here.

@xylar
xylar requested a review from jhkennedy September 10, 2017 19:28
@milenaveneziani

Copy link
Copy Markdown
Collaborator

@xylar: I followed the link on the nersc portal and things look good to me, as they are supposed to, at least. A couple of clarification points for me following this statement:

this may just be a question of adding any new classes and functions to api.rst so the documentation gets autogenerated from the docstring

So, with any new analysis task or any new function (even the internal ones, that start with _?), we need to add them to api.rst? And what does it need to happen for the documentation to be autogenerated? Do we hit the make command or is it done automatically? (sorry the simple questions..)

@xylar

xylar commented Sep 12, 2017

Copy link
Copy Markdown
Collaborator Author

@milenaveneziani,

So, with any new analysis task or any new function (even the internal ones, that start with _?), we need to add them to api.rst?

No, I think you just should add the class name and any functions other than the obvious, required ones (__init__, setup_and_check, run) that other developers would need to know about. Nothing with a _ in front. Similarly, with functions, you would only add them if you think another developer would want to know about them.

And what does it need to happen for the documentation to be autogenerated? Do we hit the make command or is it done automatically?

You go into the docs directory and do make html. This doesn't happen automatically (though maybe we can make it automatic eventually). It is "autogenerated" in the sense of you don't make the pages, they get generated from the docstrings automatically.

@xylar

xylar commented Sep 15, 2017

Copy link
Copy Markdown
Collaborator Author

I have moved design_docs to docs/design_docs as you suggest. However, I don't think we want our design documents to become part of the documentation directly. It could be helpful as a starting point for some of the documentation but these files are meant to document the process of designing new features, rather than providing documentation for developers.

@xylar

xylar commented Sep 15, 2017

Copy link
Copy Markdown
Collaborator Author

@jhkennedy, I think I might know what went wrong with your test.

#!/usr/bin/env bash

conda create --name mpas -c conda-forge python=2 numpy scipy matplotlib netCDF4 xarray dask bottleneck basemap \
  lxml nco pyproj sphinx sphinx_rtd_theme numpydoc
# I think you may be missing the pillow library here.  The README.md needs to be fixed.

git clone git@github.com:xylar/MPAS-Analysis.git xylar-mpas-a
# I think you missed checking out the correct branch here, but I'm pretty sure you 
# did that step because nothing would have worked if you hadn't
cd xylar-mpas-a/docs

make html > >(tee make.out) 2> >(tee make.err >&2)

@xylar

xylar commented Sep 15, 2017

Copy link
Copy Markdown
Collaborator Author

@jhkennedy, I can verify that I see the same errors you did when I am missing the pillow library. Could you please add that library and try again?

@jhkennedy

Copy link
Copy Markdown

@xylar I did checkout sphinx_support -- I just forgot to pull that out of my history for the gist (updated).

Adding pillow did fix all the import errors, I missed it because it's not listed in the conda install... command in README.md, so it might be good to add that to the install command (even though I now see it's listed on the line above).

Looks like it's ready!

@xylar

xylar commented Sep 16, 2017

Copy link
Copy Markdown
Collaborator Author

Thanks @jhkennedy. I fixed the README.md here. (I had actually fixed it in another PR, too, but that hasn't been merged yet.)

@xylar

xylar commented Sep 16, 2017

Copy link
Copy Markdown
Collaborator Author

@pwolfram is quite busy. @vanroekel and @milenaveneziani, anymore feedback before we merge this?

@xylar

xylar commented Sep 17, 2017

Copy link
Copy Markdown
Collaborator Author

@milenaveneziani and @jhkennedy, I went ahead and fixed up a bunch of docstrings that weren't producing nice looking documentation. Obviously, this shouldn't change the code itself in any way. Just wanted to give you a heads up...

These are now in standard numpydoc format.
The formatting is now more appropriate for sphinx autodocumentation
using the numpydoc extension.
This includes autogenerated api for all public functions and modules
other than testing.
Also describe how to build the documentation
A lot has changed since the initial pass at the API was created.
@xylar

xylar commented Sep 17, 2017

Copy link
Copy Markdown
Collaborator Author

I just updated the example results at:
http://portal.nersc.gov/project/m2833/xylar/mpas_analysis/docs/

@xylar

xylar commented Sep 17, 2017

Copy link
Copy Markdown
Collaborator Author

I will merge this tomorrow unless I get further feedback requesting changes.

This required small modifications to the formatting of the docs,
notably making headings consistent and changing to a title in the
expected format.
@xylar

xylar commented Sep 19, 2017

Copy link
Copy Markdown
Collaborator Author

At @jhkennedy's recommendation, I added our design documents at the end of the documentation. This required some minor reformatting and also the use of the recommonmark package (which is only available through pip). The README.md has been updated accordingly.

@xylar
xylar merged commit d9fbf15 into MPAS-Dev:develop Sep 19, 2017
@xylar
xylar deleted the sphinx_support branch September 19, 2017 10:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants