New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Create JSON helper for template funcs #3418

Closed
bep opened this Issue May 1, 2017 · 7 comments

Comments

Projects
None yet
2 participants
@bep
Member

bep commented May 1, 2017

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

@bep bep self-assigned this May 1, 2017

@bep bep added this to the v0.21 milestone May 1, 2017

@rdwatters

This comment has been minimized.

Show comment
Hide comment
@rdwatters

rdwatters May 1, 2017

Contributor

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}}...

Contributor

rdwatters commented May 1, 2017

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

This comment has been minimized.

Show comment
Hide comment
@bep

bep May 1, 2017

Member

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

Member

bep commented May 1, 2017

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

@bep

This comment has been minimized.

Show comment
Hide comment
@bep

bep May 1, 2017

Member

@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".

Member

bep commented May 1, 2017

@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".

bep added a commit to bep/hugo that referenced this issue May 1, 2017

tpl: Add docshelper for template funcs
And fix some other minor related issues.

Updates gohugoio#3418

@bep bep closed this in #3420 May 1, 2017

bep added a commit that referenced this issue May 1, 2017

tpl: Add docshelper for template funcs
And fix some other minor related issues.

Updates #3418

@bep bep reopened this May 1, 2017

@rdwatters

This comment has been minimized.

Show comment
Hide comment
@rdwatters

rdwatters May 1, 2017

Contributor

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. 😄

Contributor

rdwatters commented May 1, 2017

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. 😄

@rdwatters rdwatters referenced this issue May 1, 2017

Open

Add undocumented function files... #106

0 of 5 tasks complete
@bep

This comment has been minimized.

Show comment
Hide comment
@bep

bep May 1, 2017

Member

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.

Member

bep commented May 1, 2017

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

This comment has been minimized.

Show comment
Hide comment
@rdwatters

rdwatters May 1, 2017

Contributor

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.

Contributor

rdwatters commented May 1, 2017

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

This comment has been minimized.

Show comment
Hide comment
@bep

bep May 1, 2017

Member

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).

Member

bep commented May 1, 2017

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment