P24

Simple tool for documenting Svelte components.

Made to be Plundered

Fork, pillage, and plunder! Do whatever as long as you adhere to the project's permissive MIT license.

Functions

parse(options = {})

Given the component:

<!--
  ArticlePreview.svelte

  This comment is not parsed by P24. If a comment
  doesn't start with '@' then it's just a normal
  comment.
  
  Name is inferred from the file name but may be
  specified as below.
-->

<!--@component ArticleListItem
  To be slotted into either an `ArticleList` or
  `ArticleGrid` component. It presents summary
  information about the article and a preview image.
  clicking the component will take the user to the
  full article.
-->

<script context="module">
  import { base } from '$app/paths'

  //@prop toFullPath
  // Resolves a relative URL path to a full URL path
  // by prepending the application base path.
  // @module
  // @const
  export const toFullPath = (relPath) => {
    return `${base}/${relPath}`
  }
</script>

<script>
  import { setContext } from 'svelte'

  //@prop title
  // Title of the article.
  export let title

  //@prop author
  // Name of the person or people who wrote the article.
  export let author

  //@prop link
  // URL to the full article.
  export let link

  //@prop published
  // Date the article was published or falsy value if
  // not yet published.
  // @default null 
  export let published = null

  //@prop image
  // URL of the preview image or falsy value to use
  // the stock image. You may used the named slot
  // 'image' if custom HTML is needed.
  // @default null
  export let image = null

  /*@ctx article-list-item
    All details about the article including whether
    slotted image and summary were provided.
  */
  setContext('article-list-item', {
    title,
    author,
    link,
    isPublished: !!published,
    published,
    image,
    hasImageSlot: $$slots.image,
    hasSummary: $$slots.default,
  })
</script>

<article>
  <h2>{title}</h2>

  {#if $$slots.image}
    <!--@slot image
      Alternative to using the 'image' property if
      custom HTML is needed to present the article
      preview thumbnail.
    -->
    <slot name="image" />
  {:else if image}
    <img src={image} />
  {:else}
    <img src="/images/stock-article-preview-image.jpg" />
  {/if}

  <!--@slot
    Short description of the article.
  -->
  <slot />
</article>

When parsed with:

import p24 from 'p24'

const fileDocs = p24.parse()

Then fileDocs will be something similar to:

[
  {
    name: "ArticlePreview.svelte",
    description: 
    relPath: "./src/lib/ArticlePreview.svelte",
    absPath: "/home/esmerelda/github/my-project/src/lib/ArticlePreview.svelte",
    nodes: {
      name: "ArticleListItem",
      descriptions: `To be slotted into either an \`ArticleList\` or \`ArticleGrid\` component. It
presents summary information about the article and a preview image.
clicking the component will take the user to the full article.`,
      module: {
        const: {
          toFullPath: `Resolves a relative URL path to a full URL path by prepending the
application root path.`
        }
      },
      props: {
        let: {
          title: "Title of the article.",
          author: "Name of the person or people who wrote the article.",
          link: "URL to the full article.",
          published: "Date the article was published or falsy value if not yet published."
          image: `URL of the preview image or falsy value to use the stock image.
You may used the named slot 'image' if custom HTML is needed.`
        }
      },
      context: {
        'article-list-item': `All details about the article including whether slotted image and summary
were provided.`
      },
      slots: {
        image: `Alternative to using the 'image' property if custom HTML is needed to
present the article preview image.`,
        default: "Short description of the article."
      },
    }
  }
]

Options

Defaults noted as field values. For information on glob and glob options see NPM glob package (Github).

import p24 from 'p24'

p24.parse({
  // Custom prefix for nodes.
  prefix: "@",

  // For SvelteKit packaged libraries you would use
  // "dist/*.svelte" or some variation of it.
  glob: "**/*.svelte",
  globOptions: {}
})

renderReadme(options = {})

Parses the documentation then compiles a README from a template with the documentation.

By default, a template README file called README.template.md is read, placeholder text {{PLACEHOLDER}} is swapped out for the rendered documentation, before finally writing the whole thing to README.md.

Example output for a single component:

### `<Form>`

Primary component in which fields are slotted into.
$restProps are passed to the form element (outer component element).

```svelte
<script context="module">
  // Store containing fields referenced by their input names.
  export let fields = writable({})

  // Store containing values referenced by their input names.
  export let values = writable({})

  // Store containing error messages referenced by their input names.
  // An empty string represents either no error or unvalidated.
  export let errors = writable({})

  // Store containing the passed form level properties.
  // 
  // $form = {
  //    id,
  //    validate,
  //    submit,
  // }
  export let form = writable({})
</script>
```

```svelte
<script>
  // Element id of the form.
  export let id = /* = Randomly assigned ID. */

  // Function for validating all fields. It accepts a field name to value
  // object and must return a field name to errors object.
  export let validate = null

  // Function for submitting the form. It accepts a field name to value
  // object.
  export let submit = null

  // See fields property.
  setContext("p17-fields", ...)

  // See values property.
  setContext("p17-values", ...)

  // See errors property.
  setContext("p17-errors", ...)

  // See form property.
  setContext("p17-form", ...)
</script>

<!-- Form fields, buttons, and anything else you fancy. -->
<slot />
```

```svelte
<Form
  id={/* = Randomly assigned ID. */}
  validate={null}
  submit={null}
>
  <div />
</Form>
```

Options

Defaults noted as field values.

For information on glob and glob options see NPM glob package (Github).

import p24 from 'p24'

p24.parse({
  // Custom prefix for nodes.
  prefix: "@",

  // For SvelteKit packaged libraries you would use
  // "dist/*.svelte" or some variation of it.
  glob: "**/*.svelte",
  globOptions: {}

  // The name of the README template file.
  template: './README.template.md',

  // The output file name.
  output: './README.md',

  // The placeholder text in the template to swap
  // for the parsed and rendered documentation. 
  placeholder: '{{PLACEHOLDER}}',
})

CLI

This functionality is also available in CLI form allowing commands such as:

npx p24

And package.json scripts:

{
  "scripts": {
    "docs": "p24"
  }
}

With most arguments available:

npx p24 \
  --prefix "@" \
  --glob "**/*.svelte" \
  --template "README.template.md" \
  --output "README.md" \
  --placeholder "{{PLACEHOLDER}}"

Or:

npx p24 \
  -p "@" \
  -g "**/*.svelte" \
  -t "README.template.md" \
  -o "README.md" \
  -s "{{PLACEHOLDER}}"

Back Story

I simply wanted to document a component's API within itself and regenerate that documentation in a form I please, particularly within a README. To clarify, I want to document the interface (API) to the component by documenting its single implementation. Ths includes details such as its name, description, module and instance properties, slots, set context, and defaults where applicable.

A few documentation tools come close but none completely satisfy my need for simplicity, readability, flexibility, and ability to document all mentioned aspects of the API. Furthermore, existing tools traded-off too much flexibility for conciseness. So I set about creating P24. In the process I was able to separate the concern of parsing annotated comments into P23.