Coder Social home page Coder Social logo

code_excerpter's Introduction

code_excerpter

A line-based builder for extracting code regions from source files.

Documentation for a package or framework often contains code excerpts. There are two main approaches to ensuring that such code excerpts remain up-to-date as the package or framework code base evolves. (1) A literate programming approach, where code fragments are extracted from the docs, then analyzed and tested. (2) A complementary approach where named code regions are extracted from sources, and docs are refreshed (as needed) when code regions change.

Both approaches have their merits, but code_excerpter, and its companion tool code_excerpt_updater, support (2). More specifically:

  • code_excerpter is a builder that can be used to extract code regions from source files.
  • code_excerpt_updater can be used to refresh code regions inside docs using the output from code_excerpter

Usage synopsis

  1. One-time setup: define a builder config file.
  2. Markup your sources with (optionally named) code regions delimited by #docregion / #enddocregion pairs, each written inside a line comment. An example is given below.
  3. Run the builder.
  4. Use code_excerpt_updater to update your docs.

Repeat steps 2-4 as the code base evolves.

Examples sources

// #docregion imports
import 'dart:async';
// #enddocregion imports

// #docregion main, main-stub
void main() async {
  // #enddocregion main-stub
  print('Compute π using the Monte Carlo method.');
  await for (var estimate in computePi().take(500)) {
    print('π ≅ $estimate');
  }
  // #docregion main-stub
}
// #enddocregion main, main-stub

/// Generates a stream of increasingly accurate estimates of π.
Stream<double> computePi({int batch: 100000}) async* {
  // ...
}

The regions defined in the Dart source above are: imports, main, main-stub, and (implicitly) the default region named ''. If you don't explicitly delimit the default region, it is assumed to be the entire file.

Some of the regions defined in the example above include:

  • imports region:

    import 'dart:async';
  • main-stub region:

    void main() async {
      // ···
    }

The main-stub region is discontinuous, that is, it has a break in it. By default, when the code_excerpt_updater renders a region with breaks, each breaks is replaced by a (language-specific) comment line filled with a plaster marker (···).

For details concerning the processing of plasters, see the code_excerpt_updater documentation.

Notes:

  • If a code region end coincides with the file end, then its closing #enddocregion can be omitted.
  • The code_excerpter supports source files in all popular languages including Dart, HTML, YAML, CSS, SCSS, and more.

Syntax

As illustrated above, the region markers can be followed by zero or more comma-separated region names.

A legal region name is one of:

  • ''
  • A non-empty sequence of alpha-numeric characters possibly containing a hypen (-) or an underscore (_).

Sample builder config

To use the builder, create a config file such as the following:

targets:
  $default:
    sources:
      include: [examples/**]
      exclude:
        - '**/.*/**'
        - '**/build/**'
    builders:
      code_excerpter|code_excerpter:
        enabled: true

Build by running this command:

> pub run build_runner build --output=<some-directory>

Yaml files containing excerpts (*.excerpt.yaml) will be placed in the build output folder.

code_excerpter's People

Contributors

chalin avatar legalcodes avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

code_excerpter's Issues

Default plaster comment should match the docregion tag comment

Use case from toh-5/lib/app_component.dart where we put a docregion tag inside an @Component template:

// #docregion routes-and-template
@Component(
  // #enddocregion routes-and-template
  selector: 'my-app',
  // #docregion template, routes-and-template
  template: '''
    <!-- #enddocregion routes-and-template -->
    <h1>{{title}}</h1>
    <nav>
      <a [routerLink]="routes.dashboard.toUrl()"
         routerLinkActive="active">Dashboard</a>
      <a [routerLink]="routes.heroes.toUrl()"
         routerLinkActive="active">Heroes</a>
    </nav>
    <!-- #docregion routes-and-template --> 
    <router-outlet [routes]="routes.all"></router-outlet>
  ''',
  // #enddocregion template, routes-and-template
  // #docregion styleUrls
  styleUrls: ['app_component.css'],
  // #enddocregion styleUrls
  // #docregion directives
  directives: [routerDirectives],
  // #enddocregion directives
  // #docregion routes-and-template
  providers: [
    ClassProvider(HeroService),
    ClassProvider(Routes),
  ],
)
class AppComponent {
  final title = 'Tour of Heroes';
  final Routes routes;

  AppComponent(this.routes);
}

2018-06 TODO list

  • Support plaster #3
  • Add minimal useful content to README.md
  • Support, or at least warn about / reject, excerpts who first line is indented more than the rest.

Later:

  • Region name generalization: we're considering supporting quoted region names. Ensure that this is handled properly when encoding the region name as a key in the YAML file.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.