Add docs to shortcodes

[Agos95]

Purpose

Add shortcode parametrs documentation in the html files.

Documentation

Add the description of shortcode parameters at the top of each file, in order to have a more immediate view of all the options availables. The format is inspired by Python docstrings.

The change should be non-breaking, since only comments are added in the file, while the code is untouched.

[netlify]

✅ Deploy Preview for hugo-portfolio-theme canceled.

Name	Link
🔨 Latest commit	642300a
🔍 Latest deploy log	https://app.netlify.com/sites/hugo-portfolio-theme/deploys/630a977b0c6102000855ec3b

[netlify]

✅ Deploy Preview for markdown-slides canceled.

Name	Link
🔨 Latest commit	642300a
🔍 Latest deploy log	https://app.netlify.com/sites/markdown-slides/deploys/630a977b3a78cc00082cfaad

[gcushen]

Thanks for proposing an improvement by adding Python-style docstrings to document the parameters in the Go Templates.

I have a concern about the maintenance as you are essentially proposing copying the shortcode documentation from the Wowchemy website into each individual shortcode file. Whilst this might mean contributors don't need to check the website, this means that we would have 2 separate sets of shortcode documentation to maintain and keep in sync.

Python docstrings work so well in Python as it is a programming language (rather than some HTML templates), standardised, and generally a script is run to create the documentation site from the documentation in the code, so there is only one source of truth with no duplication of effort.

As the only regular maintainer currently on the project, this duplication of effort every time a shortcode is added/removed/edited is not particularly sustainable/feasible unless we have other regular maintainers. Even then, likely the two sets of documentation will end up out of sync over time.

Another approach is perhaps to improve the documentation site with clearer description of parameters and then keep your proposed doc links in the code so the shortcode documentation is all in one place?

[Agos95]

I agree about the maintenance, and actually I didn't think about it.
I also tought to propose a change in the documentation website insead of the code, but I could not find the Edit button as stated in the contributing guidelines. If you point me where I can propose the change in the website, I am going to look into it.

In my opinion, a bit more formal presentation of the parameters (maybe something like the code snippets in Build your Homepage section) can help users to have a more clear view of the option for each parameter.
But instead if you think that there is no need and that it is going to make the site too "heavy" to read, no big problem for me.

Let me know if you would like me to propose a change in the documentation!

[gcushen]

I agree about the maintenance, and actually I didn't think about it. I also tought to propose a change in the documentation website insead of the code, but I could not find the Edit button as stated in the contributing guidelines. If you point me where I can propose the change in the website, I am going to look into it.

In my opinion, a bit more formal presentation of the parameters (maybe something like the code snippets in Build your Homepage section) can help users to have a more clear view of the option for each parameter. But instead if you think that there is no need and that it is going to make the site too "heavy" to read, no big problem for me.

Let me know if you would like me to propose a change in the documentation!

Thanks, there's now an Edit button at the bottom of that docs page so you can propose improvements to it ✨

Note that most users are not software devs (but scientists etc.), so we need to try to keep the docs easy to follow and digest without much bloat. We try to make Wowchemy as easy as possible to adopt and use whilst also providing powerful flexibility and customisation/extension options for more advanced users.