extend functionality of Code Snippets Import

tk1 commented 6 years ago

Feature request

It would be very convenient

to import only a few lines of a file
to specify the begin and end of the region to be imported by regular expressions
to specify the lines to be highlighted by a regular expression

What problem does this feature solve?

If a file is big and only a few lines are interesting to demonstrate an idea, you could extract those lines easily.

When using regular expressions, you don't need to count line numbers and change them when inserting lines into the file. You could write regular expressions which match certain code lines or comments, e.g. /* start-snip */.

What does the proposed API look like?

<<< @/filepath{from=reFrom, to=reTo, inclusive=[yes|no], highlight=reHighlight}

where reXXX are regular expressions. Then the region to be extracted would start at the first match of reFrom and end at the first following match of reTo. If inclusive=yes then the matching lines are included, otherwise excluded. All the lines in the region which match reHighlight will be highlighted.

All properties should be optional:

If from and to are missing the whole file will be included
If from is given and to is missing to will be the end of the file regardless of inclusive
If from is missing and to is given, from will be the start of the file regardless of inclusive
The default value for inclusive is yes.
If highlight is missing, nothing is highlighted.

How should this be implemented in your opinion?

By extending the current Import Code Snippet Markdown functionality.

Are you willing to work on this yourself?**

I'm not proficient in Markdown extensions.

ulivz commented 6 years ago

Thanks for your interest in vuepress, but we'll refine the code snippet's API later, see:

And I don't think we should support Regular Expressions at this feature. If you want to demonstrate some of those lines that needs to be done by RE, why not writing them directly? it is obviously more intuitive.

cc @znck

tk1 commented 6 years ago

I like it more to get my example lines automatically from working code files instead of using copy & paste. If something is changed in the example code the change will carry over to the documentation automatically.

daggerok commented 5 years ago

Hi @ulivz,

I wasn't able to found in documentation example, how to include only part of source code from a real project file, which can contains a lot of noice, useless demonstration particularly in documentation...

for example

<<< @/src/main/java/com/verylong/packagename/App.java

this will include everything, so I have to create separate AppDemo.java file and include it somewhere in my documentation project. And later when that file will be changed I can forget update documentation too. So I can have not synchronized documentation in my project unless someone will found a bug..

please, let me know if you have plans to support partial code snippet in a future. Similarly like we have in asciidoctor, where in real source code file in comments we can mark from-to lines will be included in a snippet:

// some App.java file
package com.verylong.packagename;
import ...;
// other code, useless for snippet
// tag::my-subject[]
  public static void main(...) {
    // ...
  }
// end::my-subject[]

// somewhere in docs/README.adoc file
include::../src/main/java/com/verylong/packagename/App.java[tags=my-subject]

and with that documentation will contains snippet with only main method, which is very good. So, I can point only to important thinks when showing code snippets and do not need remember update also documentation if that code will be changed, it will be done automatically on next build...

otherwise, if I'll include full file:

include::../src/main/java/com/verylong/packagename/App.java[]

I will loose focus..

I think, partial code snippets -- It's really useful feature and can help avoid code snippet copy-paste and real source code reusability in documentation, during development / update as soon real functionality was changed...

Regards, Maksim

vuejs / vuepress