search

canonical / open-documentation-academy

Learn open-source software documentation skills with Canonical
https://canonical.com/documentation/open-documentation-academy
Apache License 2.0
71 stars 41 forks source link

Generic Sphinx-RST: PoC for including interactive elements in RST using java script #127

Open k-dimple opened 2 months ago

k-dimple commented 2 months ago

We want to check if we can include simple interactive elements in websites developed using reStructuredText.

Scenario: A command shown in a how-to guide uses a sample set of parameters (e.g. version, arch, ..). The allowed combination of values for each of the parameters are described ahead, but the user doesn't read it and just copies the example command and changes one parameter. This might not work since some of the parameters are inter-dependent.

So instead of giving a sample command, can we include a snippet generator that generates the correct command based on the parameters specified by the user (at runtime)?

Check if this can be done and if it works, create a proof-of-concept web page to show how it is done. A fork of an existing Sphinx based project (such as the documentation starter pack) can be used as the base for the PoC.

Possible approach: Inject raw HTML/javascript. A possibly useful discussion from stackoverflow about this is here.

davidekete commented 2 months ago

Hi @k-dimple, i'd like to work on this

k-dimple commented 2 months ago

Sure @davidekete! Feel free to work on it. I'll assign it to you, thanks!

k-dimple commented 1 month ago

@davidekete are you working on this issue? or planning to work on it sometime soon? If so, could you give us a rough estimate of by when you'll be able to do it? Thanks!

davidekete commented 1 month ago

@davidekete are you working on this issue? or planning to work on it sometime soon? If so, could you give us a rough estimate of by when you'll be able to do it? Thanks!

Hi @k-dimple, my apologies. I was away for a while, I should be able to push the changes by Monday. Thank you for your patience.

k-dimple commented 1 month ago

@davidekete no problem at all! There's no hurry, I just wanted to get an idea of whether you'll be working on it or not. Thanks! Do let me know if you have any questions.

k-dimple commented 3 weeks ago

Hi @davidekete are you still planning to work on this one? You seem to have quite a few issues assigned to you! If there's too much on your plate, we could always re-open it to see if someone else wants to work on it.

davidekete commented 3 weeks ago

Hi @davidekete are you still planning to work on this one? You seem to have quite a few issues assigned to you! If there's too much on your plate, we could always re-open it to see if someone else wants to work on it.

Hi @k-dimple, I'm currently working on this issue. It's just taking a little longer than I expected. I should be able to wrap it up soon.

k-dimple commented 3 weeks ago

Great to hear that! In that case, we can catch up whenever you are done. There's no real hurry like I mentioned earlier, but I didn't want it to be totally forgotten either! :)