Add "DRAFT" watermark (or similar) to non-stable rendered spec

[sappelhoff]

According to @franklin-feingold, this issue was brought up in a recent steering group meeting:

Intro

We are rendering the specification in several flavors, such as:

• stable ... the currently accepted version of the spec
• latest ... distinguished by a -dev appendix to the version of the spec in the header of the rendered spec. This version is not currently released/accepted, but it will become stable eventually.
• and previous versions
  • v1.2.0
  • ...

Problem

However, we are also rendering some development branches, such as the one for derivatives. Currently, this development branch "looks" similar to the "stable" rendered spec. This is a problem, because users may accidentally use this version of the specification for formatting datasets, although this is merely a development branch and subject to change.

Solution

A potential solution would be to add a watermark or similar sign to all renderings that are not either

• stable
• latest
• or previously released (outdated) version

What I have looked into so far

• potentially adding a "ribbon" to the page using html similar to the "form me on github" ribbons
  • --> turns out to be difficult with MkDocs, because we would want the ribbon only on specific versions of the specification
• Adding a watermark of some kind on top of our source during the rending process
  • --> I didn't find any READTHEDOCS options that support this

This leaves me with the only feasible option at this point: For every rendered development version (currently only derivatives), we can edit this line in the sourcecode:

bids-specification/mkdocs.yml

Line 1 in b6d7099

site_name: Brain Imaging Data Structure v1.3.0-dev

---site_name: Brain Imaging Data Structure v1.3.0-dev
+++site_name: Brain Imaging Data Structure v1.3.0-DERIVATIVES_DRAFT

Opinions and alternatives are welcome, I am not super happy with this solution.

[KirstieJane]

Thanks for writing this up @sappelhoff & for thinking about it @franklin-feingold!

The idea we had in the meeting was potentially changing the colour of the theme....that seems more customisable, right? Maybe purple rather than blue? (something like that)

Just pinging here incase anyone with read the docs skillz has ideas 😃

[effigies]

The decision to use mkdocs instead of sphinx puts us in a very difficult-to-customize situation. I think to do something like this, we'll probably need to write our own plugin.

[sappelhoff]

The decision to use mkdocs instead of sphinx puts us in a very difficult-to-customize situation

Would it be so hard to switch? We could try a "translation" in a different repo that is private for now (or at least not promoted) and check the progress ... and if we find that it's:

• possible without too much labor (see e.g., https://github.com/miyakogi/m2r)
• much nicer to add customizations
• the output is equivalent apart from some stylistic differences

... we could take down the markdown and replace with RST?

[sappelhoff]

... we could take down the markdown and replace with RST?

in a short skype call we discussed that going from markdown to RST would be a huge amount of work ... and currently not warranted.

The best course of action to solve the present issue would be to write a plugin using Python:

https://www.mkdocs.org/user-guide/plugins/

[sappelhoff]

I was checking out the different pages rendered for our spec, and realized (contrary to what I thought) that all of them have an indication of what they are.

• Stable releases have their version numbers
• Development versions have their "soon-to-be" version number with a "-dev" appendix
  • this is also true for e.g., the derivatives rendering

That got me thinking again why (for what purpose) we need the change of color theme (or watermark, or disclaimer that it's a draft).

Could you please clarify once more @KirstieJane? Is it because few people know the meaning of a version number's -dev appendix as "draft"?

[KirstieJane]

Thanks @sappelhoff - the point is that the suffix on the version is too easy to miss (and potentially the point that you made about people not knowing what the suffix means). But mostly that if you glance at the page its quite subtle. In the url there's a difference between stable and latest and if you see them together that makes sense but if you don't then you will quite likely think that "latest" is the current one.

The goal is to just make the page very quickly look very different to the accepted standard.

[effigies]

Spent a little bit poking at this. I think conditionally fiddling with CSS should be pretty easy. I'll see what I can do. If we want to have a warning banner, there isn't a good injection point in the material theme, so we might need to fork the theme. But that's not a huge problem, IMO.

[effigies]

I can do things like this with CSS:

I think it would be good to have a banner, so we can link to the PR associated with a branch, but this is something in the short term.

[sappelhoff]

thanks for the clarification @KirstieJane!

I can do things like this with CSS:

looks super nice IMO. +1 to include this

[KirstieJane]

I LOVE IT @effigies!! 🚀