ReadDoc

Insert ExDoc documentation into files.

Installation

If available in Hex, the package can be installed by adding read_doc to your list of dependencies in mix.exs:

def deps do
  [
    {:read_doc, "~> 0.1.0"}
  ]
end

Abstract

Documentation of your project can be extracted into files containing markers.

These markers are

to mark the start of an inserted docstriang and

to mark the end thereof.

Right now only @moduledoc and @doc strings can be extracted, according to if <ElixirIdentifier> refers to a module or a function.

E.g. if a file (typically README.md) contains the following content:

  Preface

     Some text

  Epilogue

running

  mix read_doc README.md

will replace Some text with the moduledoc string of My.Module.

Limitations

• Docstrings for types, macros and callbacks cannot be accessed yet.
• Recursion is not supported, meaning that a docstring containing markers will not trigger the inclusion of the docstring indicated by these markers. <!-- end @doc Mix.Tasks.ReadDoc -->

Usage:

mix read_doc [options] files...

Each file is scanned for block of lines starting with <!-- begin @doc... and endifing with <!-- end @doc.... Then the content between two matching lines is replaced with the corresponding docstring.

The following options are implemented

--silent     no messages emitted to :stderr (defaults to false)
--keep-copy  a copy of the original input file is kept by appending `.bup<n>` where n runs from 1 to the
             next available number for which no copy exists yet (defaults to false)
--fix-errors defaults to true! (deactivate via --no-fix-errors), and closing `<!-- end @doc...` lines
             with no matching `<!-- begin @doc...` are removed from the input

\s \z"`. This values is interpreted as an extended regex indicating the begin of a docstring block, where the first capture defines the module/function of the docstring <!-- \s+ end \s @doc \s ([\w.?!]+) \s+ --> \s \z"`.

                This values is interpreted as an extended regex indicating the end of a docstring block, where
                the first capture defines the module/function of the docstring

Docs at https://hexdocs.pm/read_doc.

Author

Copyright © 2018 Dave Thomas, The Pragmatic Programmers @/+pragdave, dave@pragprog.com

Robert Dober, robert.dober@gmail.com

LICENSE

Same as Elixir, which is Apache License v2.0. Please refer to LICENSE for details.