reasonml-community / bsdoc Goto Github PK

Because of #9, had to go with an own build on ubuntu, though got esy build failing with

info esy build 0.5.8 (using esy.json)
info building @opam/cppo@opam:1.6.6@f4f83858
info building @opam/ppx_derivers@opam:1.2.1@ecf0aa45
info building @opam/result@opam:1.4@dc720aef
info building @opam/seq@opam:0.2@35c16df8
info building @opam/stdlib-shims@opam:0.1.0@d957c903
info building @opam/easy-format@opam:1.3.1@54402780
error: build failed with exit code: 1
  build log:
    # esy-build-package: building: @opam/cppo@opam:1.6.6
    # esy-build-package: pwd: /home/hlegacy/.esy/3__________________________________________________________________/b/opam__s__cppo-opam__c__1.6.6-4890b2aa
    # esy-build-package: running: 'dune' 'build' '-p' 'cppo' '-j' '4'
    Error: exception Sys_error("/usr/lib/ocaml/METAS: No such file or directory")
    Backtrace:
    Raised by primitive operation at file "src/stdune/path.ml", line 878, characters 25-50
    Called from file "src/findlib.ml", line 441, characters 6-31
    Called from file "list.ml", line 93, characters 22-25
    Called from file "src/stdune/list.ml" (inlined), line 5, characters 19-33
    Called from file "src/stdune/list.ml", line 39, characters 29-39
    Called from file "src/findlib.ml", line 440, characters 4-265
    Called from file "src/findlib.ml", line 453, characters 20-37
    Called from file "src/findlib.ml", line 457, characters 2-21
    Called from file "src/lib.ml", line 1334, characters 6-34
    Called from file "src/super_context.ml", line 288, characters 4-70
    Called from file "src/gen_rules.ml", line 327, characters 6-161
    Called from file "src/fiber/fiber.ml", line 99, characters 6-13
    
    I must not segfault.  Uncertainty is the mind-killer.  Exceptions are
    the little-death that brings total obliteration.  I will fully express
    my cases.  Execution will pass over me and through me.  And when it
    has gone past, I will unwind the stack along its path.  Where the
    cases are handled there will be nothing.  Only I will remain.
    error: command failed: 'dune' 'build' '-p' 'cppo' '-j' '4' (exited with 1)
    esy-build-package: exiting with errors above...
    
  building @opam/cppo@opam:1.6.6
esy: exiting due to errors above

Not familiar with esy, but I have 4.05.0 ocaml compiler installed with opam, any suggestions here?

A heads-up: the way odoc should be driven will be changing in the near future (see ocaml/odoc#460). We'll produce some docs on the new procedure when it's been finalised to help with the transition. It's probably worth keeping an eye on that issue, which we'll update when the docs have landed.

The link to the documentation is changed when this repo was transferred:

It is correct link in the README.

It should be possible to call the odoc API directly instead of shelling out twice for every file in the project.

Command fails:

$ yarn run bsdoc support-files
yarn run v1.15.2
$ /home/risto/git/bucklescript/foobar/node_modules/.bin/bsdoc support-files
/bin/sh: /home/risto/git/bucklescript/foobar/node_modules/.bin/bsdoc: cannot execute binary file: Exec format error
error Command failed with exit code 126.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Running arch linux

While migrating https://github.com/ostera/reactor to bsdoc I realized that I was using the script there to build docs for the example modules but relying on the .cmt instead of the .cmti files.

I'd like this to be configurable, or use both by default (prefer .cmti over .cmt for same file name).

I'll let this rest for a bit and see if the problem arises again in other places.

In index.mld, change:
can wield it's powers!
to:
can wield its powers!

Hi

does this support monorepo project ?

I have some project with structure like this

. (root)
|-> rescript-x
|-> rescript-y

and want to run bsdoc in root and generated documentation by each project (x,y).

Expected:

. (root)
|-> docs
|----> rescript-x
|----> rescript-y
|-> rescript-x
|-> rescript-y

OR

does this support for generate Markdown ?

Thank you

I have a reasonml project with .rei files for each module.

This lib, together with odoc generate beautiful documentation for specific modules, but don't seem to output a Table of Contents, (i.e. a top level index.html ), as I would expect from reading odoc documentation.

At the moment this package requires a global odoc installation — by packaging it with esy we may be able to ship bsdoc with the latest version of odoc that could work for BuckleScript v6.

It would be great to have support for the current stable release of bs-platform :)

EDIT: I did manage to esy build something that uses "ocaml": "4.2.3007" + changing a bunch of other deps to use * as the version + adding a helper for Hashtbl.find_opt, but I don't really know how to proceed with using these local changes in a different project.

I'd love the ability to "leave out" chunks of the module-path.

For example, in a project named bs-slash-create, BuckleScript by default 'namespaces' the project's modules underneath a module of the same name, SlashCreate. In simple projects with only one root module, this can result in a doubled module-path, i.e. SlashCreate.SlashCreate.

When running bsdoc build SlashCreate in such a project, a directory-structure like this is produced:

./bs-slash-create $ tree docs
docs
└── SlashCreate
    └── SlashCreate
        ...
        ├── SlashCommand
        │   ├── Option
        │   │   └── index.html
        │   └── index.html
        ├── SlashCreator
        │   └── index.html
        ├── User
        │   └── index.html
        ├── UserFlags
        │   └── index.html
        └── index.html

When published to GitHub Pages, this results in URLs like:

https://by.elliottcable.name/bs-slash-create/SlashCreate/SlashCreate/index.html

Ideally, bsdoc would allow me to explicitly strip particular components, and then discard any modules that are inaccessible by the newly-stripped path (i.e. bsdoc build SlashCreate --strip SlashCreate.SlashCreate producing SlashCommand, User, etc at the top-level of the docs.)

Alternatively, at the least, it'd be nice if bsdoc respected the "namespace" field in bsconfig.json:

{
   "$schema": "https://raw.githubusercontent.com/rescript-lang/rescript-compiler/master/docs/docson/build-schema.json",
   "name": "bs-slash-create",
   "namespace": false,
   "sources": [{
      "dir": "src",
      "subdirs": true
   }],
   // ...

... and didn't produce an additional top-level SlashCreate when that is thusly configured.

Hey @Ostera thanks for this project!

I remember this being discussed in discord but I can't find the history so I'm here filing this issue. This is the output I get

Hi! Don’t know if anyone noticed 😁, but when I compile bsdoc, I get a bunch of warnings: unused opens, unused variables, shadowed identifiers and so on.

Those shadowed identifiers might be tricky, but the other stuff should be trivial. I could do a PR if you don’t mind.