search

kokkos / kokkos-core-wiki

3 stars 45 forks source link

How to document something that is still in `Experimental` #167

Closed JBludau closed 1 year ago

JBludau commented 2 years ago

So if we want to keep the documentation close to develop and the prs on develop close to documentation (that the pr would imply/require), we probably will want some 'thing' that lets us write documentation for e.g. a backend that is not yet complete. Do we have any ideas how to integrate something like this in a neat manner?

@marcinwrobel1986 is there a way to have a switch on the documentation website that would toggle displaying stuff that is marked Experimental?

marcinwrobel1986 commented 2 years ago

Hello @JBludau , If you ask me how to do that, I would create a branch experimental-backend and just put everybody's work there and keep it up to date with current develop/main, so it can be merge any time when needed. Sphinx just generates the docs on what's defined, so if you have in mind just preparing something for longer period of time and then merge to develop/main, so it then appear in official documentation I would go with a branch.

However if you have in mind some kind of an extra button on official doc's website, which after clicking on it would show all experimental stuff it sounds to me like a very custom thing. Just, to give you an idea IMHO it have to look like that:

Please, let me know if that answers your question.

dalg24 commented 2 years ago

Marcin, Jakob is referring to what we do in Kokkos core, that is implement some features in the Kokkos::Experimental:: namespace. These do not carry the same promises of stability than those in the main Kokkos:: namespace.

marcinwrobel1986 commented 2 years ago

Marcin, Jakob is referring to what we do in Kokkos core, that is implement some features in the Kokkos::Experimental:: namespace. These do not carry the same promises of stability than those in the main Kokkos:: namespace.

Ok, Damien, thanks for clarification. I understood it totally wrong then. So in that case, we could do what I am doing at the moment - create a new directive for Sphinx and call it experimental, then assign different style to it.

Please let me know if there are still any doubts.

fnrizzi commented 2 years ago

@JBludau i think we should look into this after we resolve the customization directives. Otherwise we keep adding more things to do but we should prioritize a bit. Does it make sense?

JBludau commented 2 years ago

Sure, I just wanted to kick of the discussion (OpenACC actually has this problem at the moment as more and more is integrated over the last weeks)

JBludau commented 1 year ago

We could add something similar to the DEPRECATED for Experimental. The only thing I am not sure about is if it is not a bit heavy as a marker. But maybe we can not prepend it to the line in the documentation but append it to the end?