docs: Create JSON helper for template funcs

[bep]

See #3417

The data is (almost) complete and ready to dump to JSON.

Pseudo-data:

namespace:
   collections
   funcs:
      After
        description: "After returns all the items after the first N in a rangeable list."
        aliases: ["after"]
        examples: [["in", "expected"]]

Most of the stuff above is straight forward; to get the description we would have to run the code through the GoDoc parser, which is doable and a nice-to-have.

The big motivations for the above is:

• To reduce maintenance cost.
• To make sure docs is correct and up-to date
• To make sure the examples are correct (we run them as part of the test suite).

Since we can not create content pages from data, I assume a shortcode could include this in the content pages.

/cc @moorereason @rdwatters

[rdwatters]

I could see something like this making doc maintenance much easier, so thank you.

To further my understanding, please:

I know your example is pseudocode, but I'm not sure I follow what examples: [["in", "expected"]] means. Would you mind expanding?

When you talk about creating a shortcode, are you thinking similar to the table shortcode you created with custom outputs? If we are keeping a 1-md-file-per-func model (better for SEO), maybe even a smart partial would work. Then an editor doesn't have to worry about including the shortcode within {{.Content}}...

[bep]

Partial would also of course work fine -- the examples will be clear once finished.

[bep]

@rdwatters look at https://github.com/bep/hugo/blob/e0a2b8a8ac05eed2e853e8ad2b6b1e3ba049c705/docs/data/docs.json

Scroll to bottom.

I notice I have to do a job with the JSON to make it more "lookup friendly".

[rdwatters]

Ah, got it. Thanks for the clarification.

For context, here is the new functions archetype.

https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugo-docs-concept/archetypes/functions.md

Seems like a lot of tedious work has already been undertaken by you and @moorereason, but do you think there are maintenance benefits to adding properties such as deprecated, hugoversion, and especially the signature array (see rdwatters/hugo-docs-concept#31)?

Just a thought. I'm not suggesting we automate all of it. 😄

[bep]

The info in that JSON (description coming soon) is what we know. Nothing else CAN be generated. (I could generate the signature, but it is all interface{} values, which does not make sense without manual interpretation.

What I do suggest, however:

• Drop the deprecated and signature and just put that info into method description (in JSON)
• Not sure what Hugo version is all about.

But, we should do this in some documentation related issue.

[rdwatters]

But, we should do this in some documentation related issue.

Works for me.

Not sure what Hugo version is all about.

I'm assuming my thoughts were related to versioning of docs, deprecations, etc. I'm not wedded to it if it can be automated 😄 Cheers.

[bep]

Yes, I see the value in "does this work in my Hugo?", but let us discuss that somewhere else -- that can not be "auto generated" (in an easy way).

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.