Progress toward failing CI on sphinx warnings. #11103
Conversation
| @@ -1,3 +1,4 @@ | |||
| :orphan: | |||
There was a problem hiding this comment.
Or add it to doc/source/releases/index.rst (see comment below though) ?
Or add a stub of 21.01_announce_user that links to it (and maybe script this in scripts/bootstrap_history.py ).
There was a problem hiding this comment.
That's the only outstanding comment from me, I guess that also this line needs to be updated: https://github.com/galaxyproject/galaxy/blob/dev/scripts/bootstrap_history.py#L382
There was a problem hiding this comment.
Or add it to doc/source/releases/index.rst (see comment below though) ?
This is in a commit description but the whole reason I generate this page is to link it into the release index but then there was pushback against that maybe a year ago. I think we should either link it or stop pre-generating it - I have a vague preference but either are better than just tagging this as an orphan I think. Seems like maybe we should do that in a follow up PR specifically around these release page links though right? These seem to be more controversial than I had anticipated and I've already rolled back the strict checking so we have more freedom to address these issues in a follow up PR.
doc/source/releases/index.rst
Outdated
| .. toctree:: | ||
| :maxdepth: 1 | ||
|
|
||
| 20.09_announce_user |
There was a problem hiding this comment.
I don't like the duplication of announcements, we could replace the XX.XX_announce with XX.XX_announce_user above for the releases that have them.
There was a problem hiding this comment.
These are developer release notes right? Don't we intentionally not lead with the user release notes? If we wanted to lead with user release notes - we should just not produce developer release notes?
If you don't link these links here - what about another page with the user release notes?
There was a problem hiding this comment.
These are developer release notes right?
By looking at the docs menu, that's the general (and only at the moment) release notes page, if it was for developer release notes it should go under "Developer Documentation", I think.
Don't we intentionally not lead with the user release notes?
Maybe, I don't recall the discussion though, it could be a good time to rethink given the increasing effort on the user RNs.
If we wanted to lead with user release notes - we should just not produce developer release notes?
I think this page should list the user release notes (XX_announce for 18.09 and earlier), and all user release notes already link to the detailed/dev-oriented release notes at the bottom.
Ping @hexylena
There was a problem hiding this comment.
I didn't push them as a replacement since they're different audiences, and I think devs like reading the dev notes for a rollup of the past N months work.
That said I can definitely see the duplication in the menu being suboptimal.
I guess the question is: are users (or in general people who would benefit from seeing these) finding their way to docs.galaxyproject.org? I'm not sure at all. They are mentioned in the dev docs, but, argh.
There was a problem hiding this comment.
are users (or in general people who would benefit from seeing these) finding their way to docs.galaxyproject.org? I'm not sure at all. They are mentioned in the dev docs, but, argh.
We are now directly linking to the user release notes from the Galaxy Help menu: #10960
There was a problem hiding this comment.
I don't like it in the abstract but I don't feel strongly enough to fight on this so ba7286e. Also what I do feel strongly about is the last release's user release notes were shockingly good. I hadn't seen them before yesterday and I was blown away by the effort that must have been put into them - so I have like making them more prominent in the abstract.
There was a problem hiding this comment.
/Users/john/workspace/galaxy/doc/source/releases/19.05_announce.rst: WARNING: document isn't included in any toctree
/Users/john/workspace/galaxy/doc/source/releases/19.09_announce.rst: WARNING: document isn't included in any toctree
/Users/john/workspace/galaxy/doc/source/releases/20.01_announce.rst: WARNING: document isn't included in any toctree
/Users/john/workspace/galaxy/doc/source/releases/20.05_announce.rst: WARNING: document isn't included in any toctree
/Users/john/workspace/galaxy/doc/source/releases/20.09_announce.rst: WARNING: document isn't included in any toctree
Well that didn't even fix that problem 😓 . This PR got away from itself.
There was a problem hiding this comment.
So should we mark as orphan the XX.XX_announce.rst files for 19.01 and following ?
There was a problem hiding this comment.
Same comment as above - I think we should merge this while it is green and re-tackle release issue stuff in a clean PR focused on that.
|
Already a doc issue in the merge commit 😆... and of course from that careless @jmchilton |
Or am I missing how that file is generated in someway...
I guess I always imagined we would link these but then I was told we shouldn't - so I don't even know why we're generating them to be honest then.
…kefile target. Development target uses 4 cores (I use 8 locally), shows all warnings about issues (instead of failing on first), and skips the viewcode step which isn't parallelized and doesn't really exercise anything the developer has useful control over or would need to see during doc tweaking.
jmchilton
force-pushed
the
more_docs_stuff_3
branch
from
ed031cc to
ccdbc29
Compare
jmchilton
changed the title
Builds on #11101 with a ton more sphinx fixes... in fact fixes all the warnings I think.
Conflicting this in some ways, I've got another branch that documents Pydantic models with like all their annotated data (https://github.com/jmchilton/galaxy/pull/new/pydantic_sphinx) but the plugin it uses seems a bit buggy and generates a bunch of new warnings. I guess we could bring that in and use a custom script to parse sphinx output the way Planemo does so we can filter specific problems.