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 <notifications@github.com<mailto:notifications@github.com>> 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.