Pull code snippets from live repos

[ethanblake4]

@bsutton and I discussed and came up with this syntax (in Dart, other languages would be similar):

void myFunction() {
  var x = doThing();
  // [anvil:snippet:"mysnippet"]
  var y = doOther(x);
  y += 5;
  // [anvil:endsnippet]
}

Then in the config:

...
snippets:
- https://github.com/ethanblake4/anvil.git

This would add to the template data so could be accessed like so:

{% code dart %}
{{ snippets.anvil.mysnippet }}
{% endcode %}

or perhaps even:

{% snippet anvil.mysnippet %}

and we could infer the source type.

[bsutton]

Will need some method of defining where the snippet code live.
Perhaps a subdirectory called 'snippets'?
The ability to have a directory tree of snippets might be useful.
Not quite certain what the directory structure should look like.
The test directory reflects the src layout but I"m not certain that applies here given snippets don't always apply to a particular class.
Perhaps the snippets should reflect the template names
May be a directory per template or simply a file per template.

What if we had the directory structure mimic the directory structure of the templates and then have a dart file per template.

So if you have
routing.anvil (or whatever the extention is you are using).
and
routing.dart

The snippets for routing.anvil are found in routing.dart

So

templates
   homepage/index.anvil
   routing/intro.anvil
   routing/dynamic/dynamic.anvil

snippets
  homepage/index.dart
  routing/intro.dart
  routing/dynamic/dynamic.dart

[ethanblake4]

I thought the goal was to pull the latest changes from a live project?

So, for example with conduit, we'd just specify in the Anvil config.yaml:

snippets:
- https://github.com/conduit-dart/conduit.git

Then Anvil would pull the latest version of the conduit repo when you built it, scan for snippets in its files, and pull them out. Then in the 'template' (probably just a markdown file), you'd put:

{% snippet conduit.some_snippet_name %}

Here 'conduit' is the name of the repo and 'some_snippet_name' is defined as above. This way there's no coupling between the site and the source files.

[ethanblake4]

Of course in reality, we'd probably want to use a different repo called conduit_samples or something, not the main conduit repo.

[bsutton]

My suggestion assumed that you pulled from a live project via the git link as you noted.

My suggestion was just about creating a more structured approach to storing the snippets.

One of the key tenants of my suggestion was that the snippets are part of the main repo so that they would be subject to refactoring events and we can be sure that they contain working code.

Having said that, storing them in a 'snippets' directory probably excludes them from refactoring events.

Another approach might be to put them in a separate repo as you suggested but having the build scripts upgrade the project to the latest conduit version and then run analyser to ensure the code still compiled correctly.

My primary objective is to ensure the doco has valid code samples which are notoriously hard to maintain.

FYI the main conduit doco would also benefit from this. We are currently doing this by editing in gitbooks.
It would be a nice to have for these tools to allow us to continue editing in git books but allow us to apply the code snippets.
But this suggestion probably completely changes the intended scope of this package so might be better left to another path.

[ethanblake4]

I see your point, it might not always be smart for anvil to pull master. Perhaps we just do it like dart then:

snippets:
  conduit:
    url: https://github.com/conduit-dart/conduit.git
    ref: c31df28c3cf076c9aacaed1d77f45b66bb2e01a6

That way we can pin it to a known good version.

I do think that using Anvil as a 'preprocesser' that does Markdown -> Markdown would very much change the scope and purpose, so I'm not a fan of that. I wouldn't be opposed to adding the table-of-contents generation and other stuff that GitBooks does though, if at some point we wanted to unify the conduit docs with the rest of the site.

[bsutton]

Lets leave the gitbooks stuff aside, it was just a thought in case it turned out to be really easy to do. I'm not certain I like the 'ref' idea as it feels like it will need maintenance. I'm not actually certain that there is a problem with pulling 'master' per say but we will need a separate dart project as for the idea to work the code must be compilable. I think I would rather see another dart project as a sub repo. conduit_snippets or similar. Having a separate branch just increases the chance it will be forgotten. S. Brett Sutton Noojee Contact Solutions 03 8320 8100

…

On Mon, 28 Jun 2021 at 12:19, Ethan ***@***.***> wrote: I see your point, it might not always be smart for anvil to pull master. Perhaps we just do it like dart then: snippets: conduit: url: https://github.com/conduit-dart/conduit.git ref: c31df28c3cf076c9aacaed1d77f45b66bb2e01a6 That way we can pin it to a known good version. I do think that using Anvil as a 'preprocesser' that does Markdown -> Markdown would very much change the scope and purpose, so I'm not a fan of that. I wouldn't be opposed to adding the table-of-contents generation and other stuff that GitBooks does though, if at some point we wanted to unify the conduit docs with the rest of the site. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG32ODM5WCJKMYAAWWKCV3TU7L2JANCNFSM47M7VH5Q> .

[ethanblake4]

The ref isn't necessarily a branch, I was thinking as a reference to a commit. But you're right that it's not really necessary with a separate conduit_samples repo.

…

On Sun, Jun 27, 2021, 8:39 PM Brett Sutton ***@***.***> wrote: Lets leave the gitbooks stuff aside, it was just a thought in case it turned out to be really easy to do. I'm not certain I like the 'ref' idea as it feels like it will need maintenance. I'm not actually certain that there is a problem with pulling 'master' per say but we will need a separate dart project as for the idea to work the code must be compilable. I think I would rather see another dart project as a sub repo. conduit_snippets or similar. Having a separate branch just increases the chance it will be forgotten. S. Brett Sutton Noojee Contact Solutions 03 8320 8100 On Mon, 28 Jun 2021 at 12:19, Ethan ***@***.***> wrote: > I see your point, it might not always be smart for anvil to pull master. > Perhaps we just do it like dart then: > > snippets: > conduit: > url: https://github.com/conduit-dart/conduit.git > ref: c31df28c3cf076c9aacaed1d77f45b66bb2e01a6 > > That way we can pin it to a known good version. > > I do think that using Anvil as a 'preprocesser' that does Markdown -> > Markdown would very much change the scope and purpose, so I'm not a fan of > that. I wouldn't be opposed to adding the table-of-contents generation and > other stuff that GitBooks does though, if at some point we wanted to unify > the conduit docs with the rest of the site. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#1 (comment)>, > or unsubscribe > < https://github.com/notifications/unsubscribe-auth/AAG32ODM5WCJKMYAAWWKCV3TU7L2JANCNFSM47M7VH5Q > > . > — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACLK2PDQSZ6HE4I7J3HRSN3TU7OHRANCNFSM47M7VH5Q> .