search

ODM2 / WOFpy

A server-side implementation of CUAHSI's Water One Flow service stack in Python.
http://odm2.github.io/WOFpy/
9 stars 9 forks source link

Sphinx docs reactivation, overhaul #233

Open emiliom opened 5 years ago

emiliom commented 5 years ago

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

Documentation files, documents

lsetiawan commented 5 years ago

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 commented 5 years ago

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.

:+1:

emiliom commented 5 years ago

@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 :smile_cat:

emiliom commented 5 years ago

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 commented 5 years ago

@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 :disappointed: Sorry for not being able to assist with this overhaul. Been quite busy lately with short deadlines and lots of requests!

emiliom commented 5 years ago

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 commented 5 years ago

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

lsetiawan commented 5 years ago

Can't wait to see the public docs! :smile:

emiliom commented 5 years ago

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

Thanks so much, @ocefpaf!!

emiliom commented 5 years ago

@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 commented 5 years ago

@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.

:+1: (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:

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 commented 5 years ago

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 commented 5 years ago

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.orghttp://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 @ocefpafhttps://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 GitHubhttps://github.com/ODM2/WOFpy/issues/233#issuecomment-458758237, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AE7T1OO3bEsEVm4aux7HQ5UgBZmdDT-5ks5vIOIEgaJpZM4ZnJZZ.

emiliom commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

Yikes! I'm glad that was just a misunderstanding :smile:

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 commented 5 years ago

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.