jaredly/redoc

A clean & easy documentation generator for reason/bucklescript/ocaml

Redoc

A clean & easy documentation generator for reason/bucklescript/ocaml.

Check out the generated docs at https://jaredforsyth.com/redoc.

How to use:

get the binary (either by downloading it, or building it yourself).

To build:

npm install
npm start

The binary is then in ./lib/bs/native/main.native. You can run ./redoc.sh, which delegates to that.

Common options

  --root (default: current directory)
      expected to contain bsconfig.json, and bs-platform in the node_modules
  --target (default: {root}/docs)
      where we should write out the docs
  --name (default: the name of the directory, capitalized)
      what this project is called
  --ignore-code-errors
      don't print warnings about parse & type errors in code blocks
  --ml
      assume code snippets are in ocaml syntax, not reason
  -h, --help
      print this help

Less used options

  --project-file (can be used multiple times)
      specified as /abs/path/to/.cmt:rel/path/from/repo/root
  --project-directory (can be used multiple times)
      path/to/cmt/directory:rel/path/from/root
  --dependency-directory (can be used multiple times)
      a directory containing ".cmj" files that should be '-I'd when compiling snippets
  --bs-root (default: root/node_modules/bs-platform)
  --skip-stdlib-completions
      don't include completions for the stdlib in the playground
  --no-bundle
      don't bundle the code examples. This disables editor support
  --just-input
      just parse the options & show the debug output of parsing cli args
  --debug
      output debugging information

Related work

http://davidchristiansen.dk/drafts/final-pretty-printer-draft.pdf

ooh check this out https://github.com/martinklepsch/cljdoc

redoc's Issues

Js.t objects generate invalid signatures

For example, the following code:

type point = {
  .
  "x": float,
  "y": float,
};

Generates this line of documentation:

type point = Js.t(< x : float; y : float >)

This is invalid Reason and looks to be a combination of Reason and OCaml syntax. As far as I have seen this happens for every Js.t type.

Relationship to Odoc and Ocamldoc?

Hi! What's the relationship of this project to Odoc and Ocamldoc? Perhaps it could be explained somewhere to answer the question "why does this project exist separately"?

add a "watch mode"

So when you're editing documentation, you can see the results quickly

Better support for package.json's repository field

Currently it only works if it's in the "username/reponame" format, but I'd like to support the same things that npm does https://docs.npmjs.com/files/package.json#repository
(this is for producing the "edit" links on each page)

style function arguments in PrintType.re

would be nice to have them bold or something.

Also would be good to style type names that aren't hyperlinked

maybe list all non-referenced items at the bottom of the page?

Currently if you have a module-level comment, and you don't @doc mention something, then it doesn't get rendered at all. This breaks assumptions about links...
I think maybe I should just render everything you haven't mentioned in a list at the end.

The binary distribution has hardcoded paths

The binary distribution has hardcoded paths at some point (I didn't investigate). It results in errors like:

Fatal error: exception Failure("Unable to copy ./../../../static/block-script.js to /Users/wczekalski/Documents/Work/Projects/bs-react-native/docs/block-script.js")
Raised at file "pervasives.ml", line 30, characters 22-33
Called from file "/Users/jared/clone/tools/docre/src/ModelToOutput.re", line 242, characters 4-92
Called from file "/Users/jared/clone/tools/docre/src/utils/Infix.re", line 10, characters 68-73
Called from file "/Users/jared/clone/tools/docre/src/ModelToOutput.re", line 241, characters 40-670
Called from file "/Users/jared/clone/tools/docre/src/Main.re", line 112, characters 9-15

Interactive code snippets not being generated

• docre version: master 73fb3c0 workin on the sidebar
• Source Docs: https://github.com/scull7/bs-result
• Generated docs here: https://scull7.github.io/bs-result/api/Result.html

Copious amounts of debug output:
bs-result-docre-debug-output.txt

Edit button in interactive code does not appear to work

When I click Edit in active code, the button text becomes ..., but I am not able to type in the code block, either on Firefox 61.0b5 or Chrome Version 66.0.3359.170

Generating MD files for Docusaurus

This is definitely more of a question than a bug report (or even feature request)...

I'm hoping to end up with Docusaurus docs for a library I'm working on. I'd like these docs to be a mix of hand-written "guide" pages and API docs generated from docblock comments in my code.

redoc's ability to make sense of both docblock comments and rei/mli interface files seems incredibly promising, but it generates a full HTML site, while Docusaurus expects to find Markdown pages. How suitable is redoc for this task, and where would you recommend I start digging in if I want to modify it for this use case?

Thanks for building this sweet tool!

$$$

😍😍😍😍
💸💸💸💸
🤑🤑🤑🤑

Don't build documentation for non-public directories

I have a bunch of my modules in my bsb project that reside in directories marked not public in my bsconfig. Ideally these would not be documented either in the output of docre.

Infinite loop when generating docs for a parent directory

After running ./node_modules/.bin/redoc --root .., redoc gets stuck.

docre.sh no longer works after recompile

david@linux:~/reasondocs/using_belt_set> ~/docre/docre.sh
Fatal error: exception Failure("lib/js not found")
Raised at file "pervasives.ml", line 30, characters 22-33
Called from file "/home/david/docre/src/utils/Infix.re", line 2, characters 42-53
Called from file "/home/david/docre/src/CliToInput.re", line 350, characters 71-102
Called from file "/home/david/docre/src/utils/Infix.re", line 10, characters 68-73
Called from file "/home/david/docre/src/utils/Infix.re", line 9, characters 62-67
Called from file "/home/david/docre/src/CliToInput.re", line 374, characters 18-45
Called from file "/home/david/docre/src/Main.re", line 102, characters 14-40
Called from file "/home/david/docre/src/Main.re", line 112, characters 9-15

Environment:

david@linux:~/reasondocs/using_belt_set> ls -l node_modules/bs-platform
lrwxrwxrwx 1 david users 67 May 18 11:21 node_modules/bs-platform -> /home/david/.nvm/versions/node/v10.1.0/lib/node_modules/bs-platform

After further research: it appears that if I create an empty js folder in the project’s lib directory, I no longer get the error, but don’t get docs/index.html either.

After more research: the error happens sometime between these two commits:

 3d453080442edf261d76a9649228cde2abc2dc0a # works (Apr 21) 
 64331abea4594193cd9f088b575f65c722b79a30 # doesn't work (Apr 21) 

Could this line in src/Main.re be part of the problem:

let stdlib = bucklescript.bsRoot /+ "lib/js";

search suffixes

I noticed that searching for ocamldoc in the official redoc demo doesn't find the module MarkdownToOCamldoc. I thought I would report it in case this is not expected.

How to use?

I see docs for the executable, but where does it source written documentation? I'm guessing I need to write comments in my code somewhere, are there any instructions on where and formatting?

Auto-collapse table of contents

If there are more than X items in a header, have it collapsed by default.

Can we get new bsb bundles in static

https://github.com/jaredly/redoc/tree/master/static seems to only go up to bs-3.0.0.js, which as far as I can tell, is preventing the docs from being editable when I generate them. How can we generate new ones (for 4.0.6, for example)?

Somehow getting duplicate output

Hi there,

I am getting duplicate output, any idea what could be causing this?

here with another project:

Here is a screenshot of the terminal output to create a basic demonstration of this issue:

I've stored a minimal example with output in a repo here: https://github.com/wires/redoc-issue

Maybe it is because certain directories are listed twice (see redoc_debug_output.txt:

  compiledDependencyDirectories:
    /private/tmp/test/lib/bs : /private/tmp/test/lib/js/
    /private/tmp/test/lib/bs : /private/tmp/test/lib/js/
    /private/tmp/test/lib/bs/src : /private/tmp/test/lib/js/src

run bsb from within docre

Then you wouldn't have to manually do it

Top level documentation block is never picked up

reasonml-community/bs-react-native@1051db5

An instance of the problem is here ^