Sphinx docs reactivation, overhaul

[emiliom]

Time to overhaul the Sphinx docs. This will involve a substantial update and reorganization, including:

• Ask Don for help
• (Re)activate CI to build the Sphinx docs, but targeting github-hosted docs rather than the old http://pythonhosted.org/WOFpy
• Change to support markdown files, to make it easier to edit content (like we do with the NANOOS DMAC Sphinx docs)

Documentation files, documents

• https://github.com/ODM2/WOFpy/tree/master/docs
• https://github.com/ODM2/WOFpy/tree/master/docs/Sphinx Note that UCSD added new or updated content a couple of years ago. But much of the original content is still there.
• See the content in README.md, including:
  • Documentation: WOFpy documentation is currently (2017 August-September) being overhauled. Much of the previous documentation available at http://pythonhosted.org/WOFpy is out of date and should be used with care, mainly for conceptual descriptions.
  • Installation: See this interim document for up-to-date, detailed installation and configuration instructions. Configuration examples are based on ODM2 timeseries and measurements DAO's.
• Relevant old, open issues: Add documentation info about installation on Apache #218, Add Conda Channel information to documentation #59

[lsetiawan]

Replying on your email

The one configuration change I'm interested in exploring is support for markdown files, like what you did for the NANOOS DMAC sphinx. Unless you advice against it.

I'm not sure how this would work with the auto doc and such. I think sticking with just reST would be best. You might want to consult with Filipe on this one. I remember him advising me against it before.

I do want to learn, but I also don't want to take more of your time. So, I figure by carefully studying your PR I'll learn a lot w/o having to bug you much.

That's a good start. I think as long as you follow the docs folder structure and make sure you have similar code within the travis yaml, this should work.

[emiliom]

The one configuration change I'm interested in exploring is support for markdown files, like what you did for the NANOOS DMAC sphinx. Unless you advice against it.

I'm not sure how this would work with the auto doc and such. I think sticking with just reST would be best. You might want to consult with Filipe on this one. I remember him advising me against it before.

Ok, sounds good. No markdown.

I think as long as you follow the docs folder structure and make sure you have similar code within the travis yaml, this should work.

👍

[emiliom]

@lsetiawan Have you had some time to think about whether, and possibly when, you'd be able to help with this? No pressure! I'd just like to know what you've decided, to help me plan.

FYI, I've started to do WOFpy testing and development, after wrapping my brain around how WOFpy works, the flow from a request to a response, etc. Fun 😸

[emiliom]

This comment from @ocefpaf isn't really about Sphinx, but I wanted to capture it here for my own reference:

BTW, kind of related, I started using black which became the "the facto" code formatter for python:
https://black.readthedocs.io/en/stable/

It solves the discussion, checking, review of code style for good. Just run black before committing and never worry about code format ever again.

For existing projects applying it is a huge commit and should be done only if all the contributors are on board first. (B/c of the conflicts it will create.)

[lsetiawan]

@lsetiawan Have you had some time to think about whether, and possibly when, you'd be able to help with this? No pressure! I'd just like to know what you've decided, to help me plan.

FYI, I've started to do WOFpy testing and development, after wrapping my brain around how WOFpy works, the flow from a request to a response, etc. Fun

Darn, I did not see this tag 😞 Sorry for not being able to assist with this overhaul. Been quite busy lately with short deadlines and lots of requests!

[emiliom]

No worries @lsetiawan. I figured you were very busy with your day job. Plus, @ocefpaf has extra time on his hands, due to IOOS and the federal shutdown ...

Sphinx is almost ready to go! @ocefpaf is dealing with -- hopefully -- the last glitch.

[emiliom]

See PRs #234, #235, #236 (but this one is mainly about Travis-CI and coding standards)

[lsetiawan]

Can't wait to see the public docs! 😄

[emiliom]

Woo-hoo! http://odm2.github.io/WOFpy/

Thanks so much, @ocefpaf!!

[emiliom]

@ocefpaf, would it be a major effort to port the WOFpy sphinx docs to the Alabaster theme used by the other ODM2 software (eg, http://odm2.github.io/ODM2PythonAPI/)? I'm mainly looking for a consistent look and feel. Also, eventually I'd want to enable the module navigation available on the odm2api Sphinx, but I have a hunch that configuring that is much more involved.

I'm not in any hurry on either of those changes. Just wanted to ask. If you have documentation you can point me to, or tips, that'd be great; I can start looking into doing it myself (probably not until late February). Thanks!

[ocefpaf]

@ocefpaf, would it be a major effort to port the WOFpy sphinx docs to the Alabaster

In theory no, it should be trivial. In practice... Only the Gods would know. I'll give it a try Thursday. (I'll be away tomorrow.)

I'm mainly looking for a consistent look and feel.

👍 (You may look into adding the ODM2 logo like we did for ODM2PythonAPI.)

If you have documentation you can point me to, or tips, that'd be great

The steps are:

• install the Alabaster [1] theme and;
• change the theme in the conf.py file [2].

One roadblock I can imagine is that the WofPy's conf file is old and we may need to re-create it using latest sphinx [3]. However, I would try [1-2] first before regenerating the conf file.

[1] https://github.com/ODM2/ODM2PythonAPI/blob/master/requirements-dev.txt#L1
[2] https://github.com/ODM2/ODM2PythonAPI/blob/master/docs/source/conf.py#L89
[3] https://github.com/ODM2/WOFpy/blob/master/docs/Sphinx/conf.py#L94

[emiliom]

Thanks @ocefpaf. Like I said, there's no hurry at all. I plan to follow up on those links you provided in a couple of weeks.

[aufdenkampe]

Let's hold off on redoing the look and feel. I've been thinking of redoing the main ODM2 site in Jekyl, and potentially changing the look and feel, given that it's colors don't work well with colors in our ODM2 logo. I actually was thinking of mirroring the bigcz.org<http://bigcz.org> look and feel.

…

Sent from my iPhone On Jan 29, 2019, at 6:06 PM, Emilio Mayorga <[email protected]<mailto:[email protected]>> wrote: Thanks @ocefpaf<https://github.com/ocefpaf>. Like I said, there's no hurry at all. I plan to follow up on those links you provided in a couple of weeks. - You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub<#233 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AE7T1OO3bEsEVm4aux7HQ5UgBZmdDT-5ks5vIOIEgaJpZM4ZnJZZ>.

[emiliom]

Let's hold off on redoing the look and feel. I've been thinking of redoing the main ODM2 site in Jekyl, and potentially changing the look and feel, given that it's colors don't work well with colors in our ODM2 logo. I actually was thinking of mirroring the http://bigcz.org look and feel.

Thanks for chiming in, @aufdenkampe. But keep in mind that we're talking about Sphinx software docs here. That's completely independent of any Jekyll theme you may do at odm2.org. You can see the theme we settled on over a year ago (by default) at http://odm2.github.io/ODM2PythonAPI/ No one would have the time or resources (= money) to tweak a Sphinx theme to make it match a Jekyll theme.

So, what I'm talking about here is consistency across Sphinx instances, converging on the Sphinx theme we've already been using and are familiar with. Good for consistent presentation, and also for leveraging our limited resources. The WOFpy theme is an old one carried over from the original WOFpy developers. Happy to talk about this offline if you'd like.

[aufdenkampe]

Ah, the dangers of responding to emails and GitHub issues from a phone! Somehow the full url of odm2.github.io... wasn't visible, so I mistakenly presumed you were talking about emulating the look and feel of https://odm2.github.io/www.odm2.org, which redirects to http://www.odm2.org. All that is presently done in straight-up HTML, and not easy for our team to collectively update, etc. I'm aware that Sphinx and Jekyl are different, and themes are not transferable, which is why I referred to "look and feel". I was thinking you were talking about moving to a Sphinx theme that had a similar look and feel to http://www.odm2.org. I'm glad to hear I was mistaken!

BTW, I'm really glad to hear that you've updated the docs for http://odm2.github.io/WOFpy/. It's really a great contribution, because it will help others deploy and maintain our operational WOFpy systems. Thanks!

I also strongly support the idea of moving to the same Sphinx theme as http://odm2.github.io/ODM2PythonAPI/ and http://odm2.github.io/ODM2-Admin/. I really like that theme, and it's use of the ODM2 logo, so moving WOFpy docs to that would be awesome. Thanks for suggesting it Emilio.

[emiliom]

Yikes! I'm glad that was just a misunderstanding 😄

BTW, I'm really glad to hear that you've updated the docs for http://odm2.github.io/WOFpy/. It's really a great contribution, because it will help others deploy and maintain our operational WOFpy systems. Thanks!

Actually, it's much more than a simple update! The Sphinx doc system had never been reactivated since the ODM2/BiGCZ gang took over WOFpy development. SDSC had updated some of the .rst files, but the actual web-browseable (HTML) Sphinx docs had not been generated. @ocefpaf has activated it, enabled its deployment in github as http://odm2.github.io/WOFpy/ for the first time, and added it to our CI so it's auto updated when the .rst files are updated. I have yet to make any actual content updates myself, but now we're all set and I plan to start around Friday. Majorly cool. Thank the federal government shutdown for Filipe's availability ...

I also strongly support the idea of moving to the same Sphinx theme as http://odm2.github.io/ODM2PythonAPI/ and http://odm2.github.io/ODM2-Admin/. I really like that theme, and it's use of the ODM2 logo, so moving WOFpy docs to that would be awesome. Thanks for suggesting it Emilio.

Great! The theme is fine (plus it's very common in Sphinx deployments). For me, more than liking it or disliking it, my motivations are to have a common look across Sphinx instances, and a common structure and "code base" (if you will) to make them easier to maintain and share skills/experience across our loose and underfunded team.

[aufdenkampe]

Yes, indeed. It's clear your update is really more of a massive overhaul. Thank you for undertaking the big effort to take full ownership of the docs and auto-link them to the code via Sphinx. I definitely see the exceptionally valuable benefits of that. Thank you.

We are also definitely on the same page regarding the benefits of unifying the theme with our other ODM2 Sphinx documentation, especially because that would underline the massive overhaul of the docs and change in ownership of the project. Thanks.