[Caml-list] [ANN] opkg v0.0.1 - Documentation access improvements

[Caml-list] [ANN] opkg v0.0.1 - Documentation access improvements

[Daniel Bünzli]

Hello, 

One of the goal of the `opkg` project [0] is to kill the myth 
that documentation doesn't exist in the OCaml eco-system. 
The fact is that documentation exists in many cases; it's only 
scattered and thus painful to access.

A first version of `opkg` was released just to address this problem. 
Among other things like swift access to installed change logs, 
it uses ocamldoc to generate best-effort, per package,
API docsets, relying on the mlis and cmis installed by packages. 

In a >= 4.03 switch, simply invoke :

  opam install ocaml-manual opkg 
  opkg ocamldoc
  opkg doc

Future `opkg` releases will rely on `cmti` files and use 
the maturing `odoc` effort [1] for generating API docsets.
This will notably add inter-package cross-references.

If the packages you use comply with opkg's install conventions,
there are a few other commands that you will find useful, here
applied to the bos package which satisfies them:

  opkg doc bos # Show generated API docs
  opkg changes bos # Show release notes
  opkg issues bos # Browse issues
  opkg homepage bos # Browse homepage
  opkg online-doc bos # Browse online docs

More information can be found in `opkg help basics`. 

Information on packaging conventions is in `opkg help packaging`. 
Note that these conventions are automatically enforced without 
having anything special to do if you use `topkg` [2] to release 
your packages.

Finally note that `opkg` is mostly a dumb command driver. All the 
hard work of API doc generation is being done by ocamldoc and 
credits should go to Maxence Guesdon for all the work he put in it
over the years.

Best & RTFM,

Daniel

[0] http://erratique.ch/software/opkg
[1] https://github.com/ocaml-doc
[2] http://erratique.ch/software/topkg

[Caml-list] [RE-ANN] From opkg to odig v0.0.1 (was Re: [ANN] opkg v0.0.1 - Documentation access improvements)

[Daniel Bünzli]

Hello,

Due to concerns over a binary name clash with OpenWRT's package manager [1], the opkg project  
was renamed to odig.

  http://erratique.ch/software/odig

If you have installed opkg the way out is:

 opkg cache clear
 opam remove opkg  
 opam update && opam install odig
 odig ocamldoc  
 odig doc  

Thanks to David Kaloper Meršinjak and Peter Zotov for raising
the issue.  

Sorry for the inconvenience and happy doc digging,

Daniel

P.S. To package devs if there are issues with the way your docs get rendered please get in touch on the issue tracker (if that's not due to your package install or an ocamldoc issue itself).  

[1] https://wiki.openwrt.org/doc/techref/opkg

Re: [Caml-list] [MirageOS-devel] [RE-ANN] From opkg to odig v0.0.1 (was Re: [ANN] opkg v0.0.1 - Documentation access improvements)

[Anil Madhavapeddy]

Dear all,

I have deployed an experimental documentation build for MirageOS libraries (and dependencies thereof) using odig at:

http://docs.mirage.io

an experimental build using odoc (the new cross-referencing tool that is still being worked on, so expected rendering bugs) is available under:

http://docs.mirage.io/odoc/

These URLs are all subject to change, but I thought it might be useful to see the generated output for a real project.  The Dockerfile that generates this site is at: https://github.com/mirage/mirage/blob/master/Dockerfile.doc

regards,
Anil

> On 27 Sep 2016, at 20:34, Daniel Bünzli <daniel.buenzli@erratique.ch> wrote:
> 
> Hello,
> 
> Due to concerns over a binary name clash with OpenWRT's package manager [1], the opkg project  
> was renamed to odig.
> 
>  http://erratique.ch/software/odig
> 
> If you have installed opkg the way out is:
> 
> opkg cache clear
> opam remove opkg  
> opam update && opam install odig
> odig ocamldoc  
> odig doc  
> 
> Thanks to David Kaloper Meršinjak and Peter Zotov for raising
> the issue.  
> 
> Sorry for the inconvenience and happy doc digging,
> 
> Daniel
> 
> P.S. To package devs if there are issues with the way your docs get rendered please get in touch on the issue tracker (if that's not due to your package install or an ocamldoc issue itself).  
> 
> [1] https://wiki.openwrt.org/doc/techref/opkg
> 
> _______________________________________________
> MirageOS-devel mailing list
> MirageOS-devel@lists.xenproject.org
> https://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel

Re: [Caml-list] [MirageOS-devel] [RE-ANN] From opkg to odig v0.0.1 (was Re: [ANN] opkg v0.0.1 - Documentation access improvements)

[Fabrice Le Fessant]

[-- Attachment #1: Type: text/plain, Size: 2458 bytes --]

Hi,

  Looking briefly at the two websites, the differences are not obvious. Could
you describe a little the differences between the two tools ? Is one of
them more precise than the other one ? Is one of them easier to use ?

FWIW, `ocp-browser` can also be used to browse the API/documentation of
installed packages in a terminal: see a screenshot at
https://www.typerex.org/ocp-index.html#ocp-browser

--Fabrice

On Thu, Sep 29, 2016 at 5:14 PM Anil Madhavapeddy <anil@recoil.org> wrote:

> Dear all,
>
> I have deployed an experimental documentation build for MirageOS libraries
> (and dependencies thereof) using odig at:
>
> http://docs.mirage.io
>
> an experimental build using odoc (the new cross-referencing tool that is
> still being worked on, so expected rendering bugs) is available under:
>
> http://docs.mirage.io/odoc/
>
> These URLs are all subject to change, but I thought it might be useful to
> see the generated output for a real project.  The Dockerfile that generates
> this site is at:
> https://github.com/mirage/mirage/blob/master/Dockerfile.doc
>
> regards,
> Anil
>
> > On 27 Sep 2016, at 20:34, Daniel Bünzli <daniel.buenzli@erratique.ch>
> wrote:
> >
> > Hello,
> >
> > Due to concerns over a binary name clash with OpenWRT's package manager
> [1], the opkg project
> > was renamed to odig.
> >
> >  http://erratique.ch/software/odig
> >
> > If you have installed opkg the way out is:
> >
> > opkg cache clear
> > opam remove opkg
> > opam update && opam install odig
> > odig ocamldoc
> > odig doc
> >
> > Thanks to David Kaloper Meršinjak and Peter Zotov for raising
> > the issue.
> >
> > Sorry for the inconvenience and happy doc digging,
> >
> > Daniel
> >
> > P.S. To package devs if there are issues with the way your docs get
> rendered please get in touch on the issue tracker (if that's not due to
> your package install or an ocamldoc issue itself).
> >
> > [1] https://wiki.openwrt.org/doc/techref/opkg
> >
> > _______________________________________________
> > MirageOS-devel mailing list
> > MirageOS-devel@lists.xenproject.org
> > https://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel
>
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs

[-- Attachment #2: Type: text/html, Size: 4119 bytes --]

Re: [Caml-list] [MirageOS-devel] [RE-ANN] From opkg to odig v0.0.1 (was Re: [ANN] opkg v0.0.1 - Documentation access improvements)

[Daniel Bünzli]

On Friday 30 September 2016 at 11:00, Fabrice Le Fessant wrote:
> Looking briefly at the two websites, the differences are not obvious.

The main difference is that with odoc, identifiers are linked across packages, it also should also work correctly on functor heavy code bases where ocamldoc easily starts overwriting its own outputs. Another difference is that rendering in odoc is not as good at the moment, the markup output needs reworking and some elements that should be links are not linked which poses doc usability problem and is reason why odoc is not the default doc path in odig yet.

> FWIW, `ocp-browser` can also be used to browse the API/documentation of installed packages in a terminal: see a screenshot at https://www.typerex.org/ocp-index.html#ocp-browser
Note that `odig` not only gives you access to API docs, it also gives you easy access to the readme, changelogs, homepage, issues, etc. of packages. But it shouldn't be too hard for `ocp-browser` to align on the conventions established by odig, see `odig help packaging`, you could even use the Odig API (unstable though, http://erratique.ch/software/odig/doc/).

Best, 

Daniel