Redesign snippets workflow

[0x009922]

While trying to solve hyperledger-iroha/iroha-javascript#130, I had to dive into details how snippets mechanism is currently designed (and implemented). I have some ideas that should simplify the documentation codebase (scripts part), make the whole approach more consistent with VitePress, and simplify an end-user (me) experience a bit.

My points are:

• First of all, make use of VitePress' builtin <<< snippet syntax. Some examples to illustrate its power:

  Importing whole snippet as-is:
  
  <<<@/snippets/any.ts
  
  Highlight lines:
  
  <<<@/test.rs{1,3,5-7}
  
  Extract code regions:
  
  <<<@/test.rs#lorem
  

• Use VSCode region syntax (// #region <name>) within source files instead of custom (// BEGIN FRAGMENT: <name>) syntax. It is:

  • supported by VitePress out of the box and doesn't require usage of dst-parser package (simpler code-base)
  • supported by a widely used IDE and maybe others too

• Snippets downloading - just download them into src/snippets/ dir and leave their content as is, without parsing. It will make possible to not specify any code regions in a code file if it is not necessary.

• snippet_sources.json:

  • remove version field
  • remove lang field - language is automatically inferred from the file extension. Even in the most advanced case when, for instance, the region within a Rust file effectively is an SQL, it could be solved with <<<@/sample.rs#sql-region{sql}
  • add optional name field for a file name the snippet will be written into within src/snippets/ dir. If it is omitted, then the name could be inferred from the URL.

• Remove src/snippets/meta.json - it is unnecessary.

If generalise this issue, I propose 1) to achieve generalisation by actual simplification of the codebase and 2) to not reinvent the wheel.

[outoftardis]

This approach LGTM