search

ioos / documentation-theme-jekyll

A Jekyll-based theme designed for documentation and help systems. Forked from source repo: https://github.com/tomjohnson1492/documentation-theme-jekyll for IOOS DMAC documentation use.
https://ioos.github.io/ioos-documentation-jekyll-skeleton/howto.html
0 stars 2 forks source link

Update Menu Bar/TopNav on Documentation Sites #10

Open mwengren opened 1 year ago

mwengren commented 1 year ago

Now that we've finished all the work in https://github.com/ioos/documentation-theme-jekyll/issues/3, we should update the menu bar to test everything (it's also quite ouf of date).

Changes to make to the topnav_ioos.yml file in navbars branch:

Maybe we should consider reorganizing the header/menus entirely into different categories (names are just suggestions):

Remaining To Do list (copied from comment below):

Some of the above were addressed by https://github.com/ioos/documentation-theme-jekyll/pull/13 and https://github.com/ioos/documentation-theme-jekyll/pull/14.

MathewBiddle commented 1 year ago

Add https://ioos.github.io/erddap-gold-standard/ under Software & Data Access?

mwengren commented 1 year ago

What about the Bio Workshop and/or Code Sprint pages?

Maybe we could break those out into a separate pulldown and call it 'Data Use & Community' or something? Open to suggestions.

Really we have at least three categories that could go into separate pulldowns each:

Under Data Use & Community:

Maybe we need an archive subcategory for the BioData-Training-Workshop since it's 5 years old and won't be updated. We could also link to GLOS' 2019 Code Sprint page in there: https://glos.org/2019-code-sprint/.

mwengren commented 1 year ago

The following pages should be listed somewhere at the bottom of the ioos.github.io page in an archive/deprecated list, but not linked from the top nav/menubar:

    - title: IOOS SOS Guidelines
      url: https://ioos.github.io/sos-guidelines/
    - title: IOOS Data Encoding in CSV/TSV
      url: https://ioos.github.io/ioos-csv-tsv/
    - title: Passive Acoustics Metadata
      url: https://ioos.github.io/passive-acoustics/
    - title: IOOS ncSOS
      external_url: https://github.com/asascience-open/ncSOS
    - title: IOOS i52N SOS
      external_url: https://ioos.github.io/i52n-sos/
mwengren commented 1 year ago

We still need to:

ocefpaf commented 1 year ago

@ocefpaf about gliderpy (currently links to: https://ioos.github.io/gliderpy/)?

The link will be that one. I'll publish the docs soon. Kind of dropped the ball on gliderpy in these past months.

MathewBiddle commented 1 year ago

update the sidebar menu at https:/ioos.github.io to either match the topnav, or maybe link to sections in the main page content that then contain the repo-by-repo/site-by-site links and more descriptions. Not sure we need the same list of links repeated in both places

In other sites, I treat the sidebar_nav as a way to organize the content specific to that site (section headers and subpages). As a new user, a while ago, I was confused by what the sidebar was linking to. It was a little frustrating to have the sidebar take you to a section where you had to find the proper link, when we could have simply linked to the resource there. I'm not sure what the right approach is there. Maybe leave it off? That would make it clearer you're on a home page...

update the content in the 'home' page at https://ioos.github.io/ with something better - graphics, categories matching those in topnav with brief intros etc, ...?

+100 Even just screenshots of the pages in each section would be helpful. We could make the graphics hyperlinks to the resource even.

add the deprecated resources

I agree that Passive Acoustics Metadata should be deprecated. But, I suspect the passive acoustic project will be updating that page within a year or so. Probably making the metadata piece a section of a larger documentation page about passive acoustic data management.

mwengren commented 1 year ago

In other sites, I treat the sidebar_nav as a way to organize the content specific to that site (section headers and subpages). As a new user, a while ago, I was confused by what the sidebar was linking to. It was a little frustrating to have the sidebar take you to a section where you had to find the proper link, when we could have simply linked to the resource there. I'm not sure what the right approach is there. Maybe leave it off? That would make it clearer you're on a home page...

We never put a whole lot of effort in to the content on the ioos.github.io home page, it was kind of an afterthought tbh.

I'd be in favor of dropping the sidebar entirely like you said if we could reorganize and improve what's on the main page. This is low priority so I'm probably not going to work on it any time soon. If you get some time and want to take a shot, please go for it, or maybe someone else will jump in to magically fix our docs sites beyond what we've already done...

mwengren commented 1 year ago

A quick review looks like changes were successful: https://ioos.github.io!

One straggler we must have missed: https://ioos.github.io/ioos-atn-data/, gh-pages branch: https://github.com/ioos/ioos-atn-data/tree/gh-pages.

Can you look into updating that site sometime when you have time @MathewBiddle?

And, I noticed the ioosngdac repo didn't update either: https://ioos.github.io/ioosngdac/. I'll look into that one at some point.

mwengren commented 1 year ago

Plus one more failure: https://ioos.github.io/erddap-gold-standard/

mwengren commented 1 year ago

Aaaaand, one more: https://ioos.github.io/BioData-Training-Workshop/.

It looks as though the GHA job isn't running on repos that don't have the gh-pages branch configured as the default branch and/or repos with multiple branches. For all of the above, looking back in the logs, the action hasn't been running on cron over the past few months as it should have, we just never checked.

Easiest way to see a list of those that have updated is to just browse the org repo list here: https://github.com/ioos

MathewBiddle commented 1 year ago

I think those two failed because gh-pages is not the default branch.

MathewBiddle commented 1 year ago

See https://github.com/ioos/ioos-atn-data/commit/21713e74b101e3b015926629d19af06c38b781b5: https://ioos.github.io/ioos-atn-data/

MathewBiddle commented 1 year ago

From https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule:

Scheduled workflows run on the latest commit on the default or base branch.

MathewBiddle commented 1 year ago

I think if we move the GHA into the default branch and adjust:

    - name: Git checkout
      uses: actions/checkout@v2
      with: { ref: gh-pages }

at https://github.com/ioos/erddap-gold-standard/blob/631a25d91b10e7a5cf13f0549e31f585a2b89974/.github/workflows/sync_theme.yml#L17-L19

we should be alright.

I'll test with ioos-atn-data and erddap-gold-standard and see if it works.

MathewBiddle commented 1 year ago

Worked! https://ioos.github.io/erddap-gold-standard/

MathewBiddle commented 1 year ago

I moved the GHA to the default branch and updated the action to include with: { ref: gh-pages } in the checkout step. All seems to be working as expected now.

See https://github.com/ioos/ioos-atn-data and https://github.com/ioos/erddap-gold-standard/

MathewBiddle commented 1 year ago

Completed https://ioos.github.io/BioData-Training-Workshop/. See https://github.com/ioos/BioData-Training-Workshop

MathewBiddle commented 1 year ago

We should check those repos tomorrow to see if the automation ran.

mwengren commented 1 year ago

@MathewBiddle So should we update all the sync_theme.yml files with changes to hard code use of the gh-pages branch?

I'm not 100% clear on what change to you made to the sync_theme workflow for the above repos vs what we added initially. It would be nice if they could all be consistent (not necessary they're all consistent, but it would make future maintenance easier). Can they all be consistent?

mwengren commented 1 year ago

There are differences per repo of course, such as ioos.github.io uses the main branch rather than gh-pages for the site rendering, so I guess there won't be 100% consistency no matter what.

But I guess my question is is it worthwhile to make all of the sync_theme.yml workflow files include a branch ref (for example here for ioos.github.io which would be main in this case) to match what you used for the BioData-Training-Workshop here?

mwengren commented 1 year ago

One last question hopefully: Did I do this wrong in ioos/ioosngdac by adding the workflow to the gh-pages branch rather than the master branch? Maybe this is why it's not running?

To fix that repo, the workflow would need to be moved to master and the checkout action specify using the gh-pages branch per above?

MathewBiddle commented 1 year ago

So should we update all the sync_theme.yml files with changes to hard code use of the gh-pages branch?

I'm not 100% clear on what change to you made to the sync_theme workflow for the above repos vs what we added initially. It would be nice if they could all be consistent (not necessary they're all consistent, but it would make future maintenance easier). Can they all be consistent?

But I guess my question is is it worthwhile to make all of the sync_theme.yml workflow files include a branch ref (for example here for ioos.github.io which would be main in this case) to match what you used for the BioData-Training-Workshop here?

I don't think it will break anything if we explicitly call to gh-pages branch in actions/checkout, even if it sits in the gh-pages branch. Doing so would ensure that all the sync_theme.yml files are consistent across all our doc sites, which would be nice. I think @ocefpaf mentioned that we might be able to make this it's own GHA - which would make this process easier to manage. But that might be too much overhead.

The only thing I did for those two repos was:

  1. Copy sync_theme.yml from gh-pages branch to whatever the default branch was (sometimes this was master but not always).
  2. Edited sync_theme.yml (in the default branch) to include with: { ref: gh-pages } in the actions/checkout step. https://github.com/ioos/BioData-Training-Workshop/blob/b041f3e212aab646c36e413657d301ce79d62b69/.github/workflows/sync_theme.yml#L20
  3. Commit and push the changes to the default branch. Eg. https://github.com/ioos/BioData-Training-Workshop/commit/b041f3e212aab646c36e413657d301ce79d62b69
  4. Checkout gh-pages
  5. Remove GHA from gh-pages (I just removed .github/ and all it's contents since the GHA was the only thing in there). eg, https://github.com/ioos/BioData-Training-Workshop/commit/5827932d23886d0e5411d40059a6b964370f5e52.
  6. Push gh-pages changes back up.
  7. That should kick off the GHA. If not, you should be able to manually run it in Actions.

One last question hopefully: Did I do this wrong in ioos/ioosngdac by adding the workflow to the gh-pages branch rather than the master branch? Maybe this is why it's not running?

To fix that repo, the workflow would need to be moved to master and the checkout action specify using the gh-pages branch per above?

Correct. The workflow must be in the default branch for that repo. In the ngdac repo the deafult is master: image

mwengren commented 1 year ago

Fortunately, this should affect anything we've done with the sync_theme.yml GHA, but just dropping a not here that I received this notification from GitHub that the action in one of my forked ioos.github.io repos will be disabled because it hasn't run in over 60 days. Here's the email:

[GitHub] The "sync theme submodules" workflow in mwengren/ioos-documentation-jekyll-skeleton will be disabled soon

GitHub Actions scheduled workflow

Scheduled workflows are disabled automatically after 60 days of repository inactivity. [Learn more.](https://docs.github.com/actions/managing-workflow-runs/disabling-and-enabling-a-workflow)

You can prevent sync theme submodules from being disabled on the workflows page.

I'm sure it's in their documentation somewhere. Here's the job history it's referring to:

https://github.com/mwengren/ioos-documentation-jekyll-skeleton/actions/workflows/sync_theme.yml

mwengren commented 1 year ago

Added an entry in the Remaining To Do List above with changes to make to accommodate the Glider DAC switch from /ioosngdac to /glider-dac.