dsheets / codoc Goto Github PK

View Code? Open in Web Editor NEW

34.0 34.0 5.0 6.27 MB

OCaml documentation generator

OCaml 97.03% Shell 0.04% CSS 2.94%

codoc's People

Contributors

Stargazers

Watchers

Forkers

samoht lpw25 cljoly jodonoghue ivg

codoc's Issues

Localize references to inline expansions

Resolved references always point to the maximally expanded path. Sometimes this path has an alias that is already in the local page's context and does not have any substitutions or parameterizations. When this is the case, the reference should be rewritten to point to the local definition. See ocaml-doc/doc-ock#28.

Nested module inclusion limit

Size or depth or both should probably be used to limit whether nested modules/signatures are included in a documentation page. This necessarily requires then a story regarding duplicate signatures in multiple files and what new documents are created for signature elements of a top-level module.

Classes probably should behave similarly.

Constructor/parameter indexation for types

These could be used to provide backlinks from types to their constructors and consumers. See also #16.

Remove ocamlfind-units dependency

This is entirely for the function unit_name_of_path which can be included directly into codoc.

Remove webmaster dependency

This was expedient but it is wrong.

Vertical spacing of sections inconsistent with/without labels

Stand-alone documentation comments need more bottom padding

Not enough space between the end of the comment and the next signature item.

Support for linking to external ocamldoc docs

Similar to #3 but includes compatibility support.

Indexes

Each kind of AST object (module, type, value, etc) should have its own index (if desired).

Functor arguments and with constraints

In with constraint inside functor applications, linking is a bit messy. This problems can be seen quite well in tyxml (last version) in the modules Svg_f and Html_f (also Svg_sigs.Make and the like).

For example in

module Foo (Bar: BAR) (Baz: BAZ with t = Bar.t) = ...

t links to BAZ.t and Bar.t tries to link to the functor argument but should probably link to BAR.t.

ocamlbuild not bin-annot, doesn't install cmt[i]

Should be corrected with a compiler distribution patch.

make --scheme file default?

On 02/06/2015 02:45 PM, Daniel Bünzli wrote:

Le vendredi, 6 février 2015 à 15:34, David Sheets a écrit :

There is the --scheme file option to generate all URLs with
/index.html or similar on the end which makes the docs browsable
directly from the disk.

You should rather always make the links relative and add the .html
(like ocamldoc does) this leaves the problem out, makes the tool
simpler to use, and allows too move around/consult the docs without
having to bother too much on how they might have been generated in the
first place.

The links are already relative. I might change the default but I don't think that the current default mode should disappear. It's not very nice to put '.html' or 'index.html' in your links when they are ultimately meant to be browsed on the web. There are already 3 different representations of the same resource and there will likely be more. We need to help people to talk about the resource rather than a concrete representation.

One benefit of using a local server to browse documentation is that that server can ensure what you are browsing it up-to-date. The documentation files all contain enough information to trace back to the cmti and source code so such a piece of software could achieve "refresh to regenerate" functionality.

I've open

Best,

Daniel

Subcommands for phases

Subcommands for each phase should be exposed to avoid doing unnecessary work.

Use index pages for all docs

Better for the URLs.

opam doc should work with opam 1.2.0

Somehow it manages only to produce the docs for ocaml. Any idea ? (n.b. there is a strange .0.4.0 package in the list of packages).

/Users/dbuenzli/.opam/doc/build/ocaml/asmcomp/asmgen.cmti
[...]
/Users/dbuenzli/.opam/doc/build/ocaml/utils/warnings.cmti
Fatal error:
Sys_error("Broken pipe")
Backtrace:
  Called from file "list.ml", line 73, characters 12-15
  Called from file "client/opamClient.ml", line 577, characters 6-217
  Called from file "map.ml", line 168, characters 20-25
  Called from file "map.ml", line 168, characters 10-18
  Called from file "map.ml", line 168, characters 10-18
  Called from file "map.ml", line 168, characters 10-18
  Called from file "map.ml", line 168, characters 10-18
  Called from file "core/opamFilename.ml", line 330, characters 12-15
Fatal error: exception Sys_error("Broken pipe")
Called from file "pervasives.ml", line 482, characters 30-33
Called from file "pervasives.ml", line 487, characters 2-15
Called from file "client/opamMain.ml", line 29, characters 2-22
codoc: too many arguments, don't know what to do with `ounit', `type_conv',
       `base-bytes', `sexplib', `fieldslib', `base-threads', `base-unix',
       `ssl', `react', `base-no-ppx', `optcomp', `cppo', `lwt',
       `ocplib-endian', `cstruct', `camomile', `ipaddr', `cmdliner', `re',
       `ctypes', `stringext', `base64', `uri', `uutf', `menhir', `conduit',
       `js_of_ocaml', `xmlm', `uuidm', `easy-format', `cohttp',
       `extlib-compat', `ocp-build', `biniou', `ocamlgraph', `cudf',
       `yojson', `zed', `dumpast', `hex', `jsonm', `base-bigarray', `dose',
       `ulex', `atd', `ocp-indent', `lambda-term', `assemblage', `ezjsonm',
       `dyntype', `omd', `opam-lib', `atdgen', `doc-ock-lib', `cow', `gg',
       `github', `merlin', `doc-ock-xml', `tsdl', `hevea', `uucp', `fut',
       `vg', `uucd', `uunf', `jsont', `codoc', `webglue', `opam-publish',
       `uuseg', `dicomm', `useri', `pkgopkg', `.0.4.0',
       `/Users/dbuenzli/.opam/doc/build/ocamlfind', `camlp4', `ounit',
       `type_conv', `base-bytes', `sexplib', `fieldslib', `base-threads',
       `base-unix', `ssl', `react', `base-no-ppx', `optcomp', `cppo', `lwt',
       `ocplib-endian', `cstruct', `camomile', `ipaddr', `cmdliner', `re',
       `ctypes', `stringext', `base64', `uri', `uutf', `menhir', `conduit',
       `js_of_ocaml', `xmlm', `uuidm', `easy-format', `cohttp',
       `extlib-compat', `ocp-build', `biniou', `ocamlgraph', `cudf',
       `yojson', `zed', `dumpast', `hex', `jsonm', `base-bigarray', `dose',
       `ulex', `atd', `ocp-indent', `lambda-term', `assemblage', `ezjsonm',
       `dyntype', `omd', `opam-lib', `atdgen', `doc-ock-lib', `cow', `gg',
       `github', `merlin', `doc-ock-xml', `tsdl', `hevea', `uucp', `fut',
       `vg', `uucd', `uunf', `jsont', `codoc', `webglue', `opam-publish',
       `uuseg', `dicomm', `useri', `pkgopkg', `.0.4.0'
Usage: codoc extract [OPTION]... PATH
Try `codoc extract --help' or `codoc --help' for more information.
'codoc extract -f --index --package ocamlfind camlp4 ounit type_conv base-bytes sexplib fieldslib base-threads base-unix ssl react base-no-ppx optcomp cppo lwt ocplib-endian cstruct camomile ipaddr cmdliner re ctypes stringext base64 uri uutf menhir conduit js_of_ocaml xmlm uuidm easy-format cohttp extlib-compat ocp-build biniou ocamlgraph cudf yojson zed dumpast hex jsonm base-bigarray dose ulex atd ocp-indent lambda-term assemblage ezjsonm dyntype omd opam-lib atdgen doc-ock-lib cow gg github merlin doc-ock-xml tsdl hevea uucp fut vg uucd uunf jsont codoc webglue opam-publish uuseg dicomm useri pkgopkg .0.4.0 /Users/dbuenzli/.opam/doc/build/ocamlfind camlp4 ounit type_conv base-bytes sexplib fieldslib base-threads base-unix ssl react base-no-ppx optcomp cppo lwt ocplib-endian cstruct camomile ipaddr cmdliner re ctypes stringext base64 uri uutf menhir conduit js_of_ocaml xmlm uuidm easy-format cohttp extlib-compat ocp-build biniou ocamlgraph cudf yojson zed dumpast hex jsonm base-bigarray dose ulex atd ocp-indent lambda-term assemblage ezjsonm dyntype omd opam-lib atdgen doc-ock-lib cow gg github merlin doc-ock-xml tsdl hevea uucp fut vg uucd uunf jsont codoc webglue opam-publish uuseg dicomm useri pkgopkg .0.4.0 -o my-opam-doc' exited with code 1

Extraction complete. Linking...

Linking complete. Rendering...

Rename to codoc

ocamlary is too long and confuses people/doesn't contain 'doc'.

Packages with names of depth > 1 fail

They should be just as usable.

Remove assemblage 0.4.0 dependency

Can just commit the generated files...

Figure out what to do with file and doc references

Use doc-ock instead of opam-doc-base

Stacked functions

Break at a sensible location.

opam doc should have more arguments like codoc's scheme

Related to #46 and #48.

Named doc packages and nested indexes

Let users have more control over the doc file namespace.

Add index subcommand for index file manipulations

Without this, the behavior of --index is only available during other subcommands.

opam doc --serve should be better

--serve shouldn't have to come first.

Short functors for functor structs

Use the short functor syntax for exposed functor structs.

opam doc should not look in build if cmti in lib

Let authors decide what gets documented!

Fix class and class type generation

Should be almost identical to modules. At least put in the object .. end syntax for FSM's sake!

Stacked functors

With enough functors, word wrap kicks in and the multi-ary functor signature gets harder to read. After a couple functors, they should probably be stacked.

Inlining and Interface Hiding Control

See lpw25/opam-doc-base#70.

html subcommand should be --package savvy

Doesn't re-render parent indexes correctly, doesn't render "Up" links and doesn't know about rooted package path.

Section references should use section titles

not the reference id!

Functor argument identifier anchors

A bit tricky with the outer-wrapper-for-floating-toolbar requirement.

Support templated document generation

It is common to want to customize generated documents with some boilerplate including style sheet references or overrides. Ideally, a default template would also be shipped and used for maximal ease-of-use.

Support for linking to other docs in group

Can't build docs for conduit

/home/dsheets/.opam/doc/build/conduit.0.7.1/_build/lib/conduit.cmti
about to xmlize Conduit
codoc: internal error, uncaught exception:
       Failure("couldn't find unit for root Map")

'codoc doc --package conduit.0.7.1 /home/dsheets/.opam/doc/build/conduit.0.7.1 -o test-opam-glue' exited with code 1

Support STOP comments

Missing >1 module constraints

Any constraints after the first are missing.

Hover anchor links for easy reference

When hovering an identified entity declaration, provide a link to that entity's fragment.

Portable and functional stylesheet

Default and command-line configurable.

Doc and package HTML indexes

These should exist.

issue with cow

#=== ERROR while installing codoc.0.2.0 =======================================#
# opam-version 1.2.1
# os           darwin
# command      make
# path         /Users/thomas/.opam/doc/build/codoc.0.2.0
# compiler     4.02.1+doc
# exit-code    2
# env-file     /Users/thomas/Downloads/codoc-64891-d2d111.env
# stdout-file  /Users/thomas/Downloads/codoc-64891-d2d111.out
# stderr-file  /Users/thomas/Downloads/codoc-64891-d2d111.err
### stdout ###
# codocEnvironment.cmx      <= compile-native unit-codocEnvironment-lib-codoc
# [...]
# codoc.cmxa codoc.a        <= archive-native lib-codoc
# codoc.cmxs                <= archive-shared lib-codoc
# codocCli.cmi              <= compile-byte unit-codocCli-bin-codoc
# codocConfig.cmi codocConfig.cmo <= compile-byte unit-codocConfig
# codocCli.cmo              <= compile-byte unit-codocCli-bin-codoc
# codocSysUtil.cmi codocSysUtil.cmo <= compile-byte unit-codocSysUtil
# codocCliExtract.cmi codocCliExtract.cmo <= compile-byte unit-codocCliExtract-bin-codoc
# codocCliLink.cmi codocCliLink.cmo <= compile-byte unit-codocCliLink-bin-codoc
# codocCliHtml.cmi codocCliHtml.cmo <= compile-byte unit-codocCliHtml-bin-codoc
### stderr ###
# File "_build/bin-codoc/codocCliHtml.ml", line 69, characters 2-21:
# Error: Unbound value Cow.Html.output_doc
# make[1]: *** [_build/bin-codoc/codocCliHtml.cmo] Error 2
# make: *** [all] Error 2

Root provenance chain links

They are wrong and should be correct relative paths (and the useful components of the chain should be exposed).

Add tool tests

The command-line tool's behaviors and outputs should all be tested automatically.

Make --index a simple flag

It takes an argument right now which is confusing and has muddled semantics.

-f to force overwrite ineffective

It's not needed to overwrite files... this is wrong.

Don't linkify path components.

I argue that most of the time you want to get to the definition of the last component of the path (i.e. final, type, value or module). However currently codoc linkifyes each component, because of Fitts's law it makes it hard to reach that target --- especially since our type names are often called t.

When I have M2.M1.t, I really have to aim to click on that little t to get to what I want. This makes my browsing very slow and I hate that. I think you should link the whole path to the final component only (N.B. the behaviour I describe I actually ocamldoc's one).

Going up in the hierarchy is quick enough if you need to: after you got to the def scroll up once to the top and then it's all about clicking on up/up once or twice (but again it's most of the time it's not what you are interseted in).