search

simonsobs / sisock

Sisock ('saɪsɒk): streaming of Simons Obs. data over websockets for quicklook
Other
2 stars 0 forks source link

Create sphinx documentation #9

Closed BrianJKoopman closed 5 years ago

BrianJKoopman commented 5 years ago

I wanted to get Sphinx compiling documentation. I've never used the autosummary extension, so I'm not quite sure what to expect from it. I've made some minor tweaks to get things compiling and to describe the DataNodeServer, but wanted to open this just to point out the branch, so that we could check the initial documentation already in base.py and perhaps hub.py works as intended.

ahincks commented 5 years ago

OK, I've got it making now without any warnings.

I also changed the html_style, but feel free to change it back if you prefer the other one or it clashes with what we're using for other things.

Only one bug remains, which is that the variables name and description of sisock.base.DataNodeServe show up in the body of the documentation. I don't know how to fix it. If you can figure it out, great, but I'm not going to spend more time on it now.

mhasself commented 5 years ago

The latest version (87a3cb) doesn't work for me (nor does the previous commit) -- the auto-generated stuff does not render at all. Is there a file missing? I don't know what source/modules (listed in index.rst) is supposed to point to.

Can we review the "SO Dev Guide" recommendation to use google style docstrings... Are we doing that here? Not clear to me given that napoleon extension is enabled, but "napoleon_google_docstring = False" in conf.py. If we aren't using google doc strings... which way is better? We can change the Dev Guide recommendation.

Also I think the "todo" module is useful... Why was it removed from the conf?

ahincks commented 5 years ago

The latest version (87a3cb) doesn't work for me (nor does the previous commit) -- the auto-generated stuff does not render at all. Is there a file missing? I don't know what source/modules (listed in index.rst) is supposed to point to.

Yes, I forgot to add those files. Most recent commit has them.

Can we review the "SO Dev Guide" recommendation to use google style docstrings... Are we doing that here? Not clear to me given that napoleon extension is enabled, but "napoleon_google_docstring = False" in conf.py. If we aren't using google doc strings... which way is better? We can change the Dev Guide recommendation.

It uses numpy docstrings rather than google docstrings, though I note that the type of docstring has not actually been specified in the user guide. Now is the time to choose if we want to be strict about google vs. numpy: if everything is to be in google I can translate everything. Regardless, I believe napoleon is required for both google or numpy, otherwise sphinx requires basic rst which is harder to read in the code and more cumbersome to write.

Also I think the "todo" module is useful... Why was it removed from the conf?

Through ignorance. Has been added back in in the most recent commit.

ahincks commented 5 years ago

So, @mhasself, I presume that's a green light for numpy docstrings? Are you going to suggest that it be the style, or one of the possible styles?

mhasself commented 5 years ago

Oh ya, that. The two styles are so similar (comparing this and this). Personally I have a mild preference for google, because it's more compact. How would you all feel about, officially:

BrianJKoopman commented 5 years ago

Built fine for me too, looks good. I sort of prefer the theme over the default alabaster one too. Going to merge with master.

ahincks commented 5 years ago

Oh ya, that. The two styles are so similar (comparing this and this). Personally I have a mild preference for google, because it's more compact. How would you all feel about, officially:

  • recommending google-style
  • accepting numpy-style.
  • strongly advising that any single code-base picks only one style, and states which style it is in their README.?

I'd actually suggest choosing one, otherwise it could be confusing for people who are writing docstrings for multiple repos (e.g., Brian right now!). I'm fine with the Google style (I only used numpy since I was more familiar with it) and could go through and update the docstrings: better now when the code base is still manageable. (From what I've seen of ocs docstrings, they're in neither Google nor numpy &ldots; not sure how much work updating those will be.)

What do you think?

BrianJKoopman commented 5 years ago

I sort of agree we should just pick one of the two. I unfortunately have been used to which ever format I first read about when I started using Sphinx, so I'm probably the guilty party for the non-conforming ocs docstrings. I've been meaning to read up on the Google style and will update the ocs docstrings that I wrote when I do.