dsheets / codoc Goto Github PK
View Code? Open in Web Editor NEWOCaml documentation generator
OCaml documentation generator
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
.
--serve
shouldn't have to come first.
ocamlary is too long and confuses people/doesn't contain 'doc'.
Similar to #3 but includes compatibility support.
They should be just as usable.
Would look cleaner and be easier to read.
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.
The command-line tool's behaviors and outputs should all be tested automatically.
Without this, the behavior of --index
is only available during other subcommands.
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.
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
When hovering an identified entity declaration, provide a link to that entity's fragment.
Not enough space between the end of the comment and the next signature item.
Use the short functor syntax for exposed functor structs.
Subcommands for each phase should be exposed to avoid doing unnecessary work.
Should be corrected with a compiler distribution patch.
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...
Can just commit the generated files...
Default and command-line configurable.
Any constraints after the first are missing.
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).
#=== 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
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.
These could be used to provide backlinks from types to their constructors and consumers. See also #16.
Doesn't re-render parent indexes correctly, doesn't render "Up" links and doesn't know about rooted package path.
Should be almost identical to modules. At least put in the object .. end
syntax for FSM's sake!
Let users have more control over the doc file namespace.
This is entirely for the function unit_name_of_path
which can be included directly into codoc.
Let authors decide what gets documented!
It takes an argument right now which is confusing and has muddled semantics.
A bit tricky with the outer-wrapper-for-floating-toolbar requirement.
not the reference id!
These should exist.
It's not needed to overwrite files... this is wrong.
Each kind of AST object (module, type, value, etc) should have its own index (if desired).
This is probably an OCaml parser bug as ocamldoc behaves the same way.
Better for the URLs.
/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
This was expedient but it is wrong.
Break at a sensible location.
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.
They are wrong and should be correct relative paths (and the useful components of the chain should be exposed).
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.