monoapi Documentation

[Jonathan Pryor]

After hunting around for a bit (wondering why my openSUSE monodoc had
mono embedding documentation but not my local build), I found that
mono/mono/docscripts generates the monoapi{.source,.tree.zip} files
needed to display mono embedding documentation within monodoc.

The downside is that these files are NOT built and installed as part of
the normal build process, they require special handling.  And since
we've merged the monodoc & mcs modules for Mono 2.2, I don't think this
"special handling" will be valid anymore (particularly wrt the
monodoc.xml changes -- monoapi.source will need _some_ (minor) changes
to display documentation in the right spot).

Thus, a question/proposal; could we:

1. Move mono/mono/docscripts/* into mono/docs.
2. Change mono/Makefile.am so that docs is built *after* runtime.
   This looks safe, as mono/docs/Makefile.am doesn't really do anything.
3. Always build/install the monoapi documentation as part of the normal
   build process.
4. Update the RPM .spec file to install the monoapi files
   (necessary so that we don't "lose" the monoapi documentation between
   2.0 and 2.2.)

(1), (2), and (4) should be quite straightforward; it's (3) I worry
about; is there a way to "safely" use mcs-located tools from mono as
part of the build process?  I *think* I should be able to use
$(mcs_topdir) and $(builddir) to launch managed apps, e.g.

        $(builddir)/runtime/mono-wrapper \
          $(mcs_topdir)/tools/mdoc/mdoc.exe ...

Though I'm not entirely sure if this is fully supported...

Thanks,
 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Jonathan Pryor]

On Wed, 2008-10-29 at 11:33 -0400, Jonathan Pryor wrote:
> After hunting around for a bit (wondering why my openSUSE monodoc had
> mono embedding documentation but not my local build), I found that
> mono/mono/docscripts generates the monoapi{.source,.tree.zip} files
> needed to display mono embedding documentation within monodoc.
...

> Thus, a question/proposal; could we:
>
> 1. Move mono/mono/docscripts/* into mono/docs.
> 2. Change mono/Makefile.am so that docs is built *after* runtime.
>    This looks safe, as mono/docs/Makefile.am doesn't really do anything.
> 3. Always build/install the monoapi documentation as part of the normal
>    build process.
> 4. Update the RPM .spec file to install the monoapi files
>    (necessary so that we don't "lose" the monoapi documentation between
>    2.0 and 2.2.)
>
> (1), (2), and (4) should be quite straightforward; it's (3) I worry
> about;

Not quite as bad as I feared.

Please see the attached patch.

Thanks,
 - Jon


[mono-docs.patch]

---

Index: ChangeLog
===================================================================
--- ChangeLog (revision 116512)
+++ ChangeLog (working copy)
@@ -1,3 +1,8 @@
[phone]  Jonathan Pryor  <jpryor@...>
+
+ * Makefile.am: Build `docs` after `runtime`, so that it can depend
+  upon mdoc.exe for it's operation.
+
 2008-10-20  Jonathan Pryor  <jpryor@...>
 
  * scripts/mod.in: Remove bash-isms.
Index: Makefile.am
===================================================================
--- Makefile.am (revision 116260)
+++ Makefile.am (working copy)
@@ -1,11 +1,11 @@
 AUTOMAKE_OPTIONS = foreign
 ACLOCAL_AMFLAGS = -I .
 
-SUBDIRS = po $(libgc_dir) $(eglib_dir) mono $(ikvm_native_dir) support docs data runtime scripts man samples web msvc
+SUBDIRS = po $(libgc_dir) $(eglib_dir) mono $(ikvm_native_dir) support data runtime scripts man samples web msvc docs
 
 # Keep in sync with SUBDIRS
 ## 'tools' is not normally built
-DIST_SUBDIRS = po libgc $(eglib_dir) mono ikvm-native support docs data runtime scripts man samples web tools msvc
+DIST_SUBDIRS = po libgc $(eglib_dir) mono ikvm-native support data runtime scripts man samples web tools msvc docs
 
 EXTRA_DIST= nls.m4 po.m4 progtest.m4 mono-uninstalled.pc.in dtrace-prelink.sh build-mingw32.sh LICENSE mkinstalldirs
 

Property changes on: docs
___________________________________________________________________
Modified: svn:ignore
   - Makefile
Makefile.in
   + convert.exe*
html
Makefile
Makefile.in
monoapi.tree
monoapi.zip



Property changes on: docs/sources
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/toc.xml
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/documented
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/api-style.css
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/wapi
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/check-coverage
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/check
___________________________________________________________________
Added: svn:mergeinfo

Index: docs/monoapi.make
===================================================================
--- docs/monoapi.make (revision 0)
+++ docs/monoapi.make (revision 0)
@@ -0,0 +1,12 @@
+thisdir = docs
+SUBDIRS =
+include $(topdir)/build/rules.make
+
+assemble: toc.xml
+ $(MDOC) assemble -o monoapi -f hb toc.xml
+
+convert.exe: convert.cs AgilityPack.dll
+ $(CSCOMPILE) -out:$@ $< -r:AgilityPack.dll
+
+.doc-stamp:
+

Property changes on: docs/public
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/ignore
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/convert.cs
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/public-api
___________________________________________________________________
Added: svn:mergeinfo

Index: docs/ChangeLog
===================================================================
--- docs/ChangeLog (revision 116260)
+++ docs/ChangeLog (working copy)
@@ -1,3 +1,22 @@
[phone]  Jonathan Pryor  <jpryor@...>
+
+ * . (svn:ignore), deploy (svn:ignore): Ignore generated files.
+ * AgilityPack.dll, api-style.css, ChangeLog, check, check-coverage,
+  convert.cs, current-api, deploy, documented, exdoc, ignore,
+  mono-api-metadata.html, monoapi.source, produce-lists, public,
+  public-api, README, sources, toc.xml, TODO, wapi: Copy from
+  ../mono/docscripts.
+ * exdoc: Use the in-tree mono program to run convert.exe.
+ * Makefile.am: Mention files to clean/distribute; extract
+  documentation (with exdoc) and then assemble documentation (with
+  monoapi.make's assemble target) for use by monodoc.
+ * monoapi.make: Added; Makefile to use mcs' buid/rules.make to compile
+  convert.cs and assemble documentation.  (This is a separate file so
+  that we can include mcs' build/rules.make, which needs topdir set to
+  behave properly BUT must be $(mcs_topdir) from Makefile.am's
+  perspective.)
+ * monoapi.source: Add a /monodoc/node element for use with monodoc 2.2.
+
 2006-11-19  Miguel de Icaza  <miguel@...>
 
  * exdoc: Move to use CSS instead of tables, this will break

Property changes on: docs/ChangeLog
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/current-api
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/deploy
___________________________________________________________________
Modified: svn:ignore
   - *.html

   + .stamp
*.html
api-style.css

Added: svn:mergeinfo


Property changes on: docs/produce-lists
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/README
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/mono-api-metadata.html
___________________________________________________________________
Added: svn:mergeinfo

Index: docs/monoapi.source
===================================================================
--- docs/monoapi.source (revision 116260)
+++ docs/monoapi.source (working copy)
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
 <monodoc>
+  <node label="Mono Embedding" name="embed" parent="libraries"/>
   <source provider="xhtml" basefile="monoapi" path="embed"/>
 </monodoc>

Property changes on: docs/monoapi.source
___________________________________________________________________
Added: svn:mergeinfo

Index: docs/exdoc
===================================================================
--- docs/exdoc (revision 116260)
+++ docs/exdoc (working copy)
@@ -135,7 +135,7 @@
 </html>
 EOF
  close OUT;
- system ("mono convert.exe $dir/html/$name $dir/html/x-$name");
+ system ("../runtime/mono-wrapper convert.exe $dir/html/$name $dir/html/x-$name");
 
  # clean up the mess that AgilityPack does, it CDATAs our CSS
  open HACK, "$dir/html/x-$name" || die "Could not open $dir/html/x-$name";

Property changes on: docs/exdoc
___________________________________________________________________
Added: svn:mergeinfo


Property changes on: docs/TODO
___________________________________________________________________
Added: svn:mergeinfo

Index: docs/Makefile.am
===================================================================
--- docs/Makefile.am (revision 116260)
+++ docs/Makefile.am (working copy)
@@ -1,14 +1,33 @@
+sourcesdir = $(prefix)/lib/monodoc/sources
+
+sources_DATA = \
+ monoapi.source \
+ $(ASSEMBLED_DOCS)
+
+ASSEMBLED_DOCS = \
+ monoapi.tree monoapi.zip
+
 EXTRA_DIST = \
  abc-removal.txt \
+ AgilityPack.dll \
  aot-compiler.txt \
+ api-style.css \
  assembly-bundle \
+ check \
+ check-coverage \
+ convert.cs \
+ current-api \
+ deploy \
+ documented \
  embedded-api \
  exception-handling.txt \
  exceptions \
+ exdoc \
  file-share-modes \
  gc-issues \
  gc-variables-in-c \
  glossary.txt \
+ ignore \
  internal-calls \
  ir-desc \
  jit-imt \
@@ -19,17 +38,56 @@
  magic.diff \
  mini-doc.txt \
  mini-porting.txt \
+ mono-api-metadata.html \
  mono_handle_d \
+ monoapi.make \
+ monoapi.source \
  new-regalloc \
  object-layout \
  opcode-decomp.txt \
  precise-gc \
+ produce-lists \
+ public \
+ public-api \
+ README \
  release-notes-1.0.html \
  remoting \
  ssapre.txt \
  stack-alignment \
  stack-overflow.txt \
+ thread-safety.txt \
  threading \
- thread-safety.txt \
+ toc.xml \
+ TODO \
  tree-mover.txt \
  unmanaged-calls
+
+dist-hook:
+ $(mkdir_p)  $(distdir)/sources
+ $(mkdir_p)  $(distdir)/svgs
+ cp sources/*  $(distdir)/sources
+ cp svgs/*     $(distdir)/svgs
+
+CLEANFILES = \
+ convert.exe* \
+ deploy/.stamp \
+ $(wildcard deploy/*) \
+ $(ASSEMBLED_DOCS)
+
+clean-local:
+ -rm -Rf html
+
+monoapi.tree monoapi.zip: monoapi.make Makefile.am toc.xml deploy/.stamp
+ cp api-style.css deploy
+ $(MAKE) -f $< topdir=$(mcs_topdir) assemble
+
+deploy/.stamp: convert.exe Makefile.am
+ $(mkdir_p) html
+ perl exdoc -h . ../mono/*/*.c
+ touch $@
+
+extract : deply/.stamp
+
+convert.exe: monoapi.make convert.cs Makefile.am
+ $(MAKE) -f $< topdir=$(mcs_topdir) convert.exe
+

Property changes on: docs/AgilityPack.dll
___________________________________________________________________
Added: svn:mergeinfo

---

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Miguel de Icaza-4]

Hey!

    Great work, this looks good to me!

> On Wed, 2008-10-29 at 11:33 -0400, Jonathan Pryor wrote:
> > After hunting around for a bit (wondering why my openSUSE monodoc had
> > mono embedding documentation but not my local build), I found that
> > mono/mono/docscripts generates the monoapi{.source,.tree.zip} files
> > needed to display mono embedding documentation within monodoc.
> ...
> > Thus, a question/proposal; could we:
> >
> > 1. Move mono/mono/docscripts/* into mono/docs.
> > 2. Change mono/Makefile.am so that docs is built *after* runtime.
> >    This looks safe, as mono/docs/Makefile.am doesn't really do anything.
> > 3. Always build/install the monoapi documentation as part of the normal
> >    build process.
> > 4. Update the RPM .spec file to install the monoapi files
> >    (necessary so that we don't "lose" the monoapi documentation between
> >    2.0 and 2.2.)
> >
> > (1), (2), and (4) should be quite straightforward; it's (3) I worry
> > about;
>
> Not quite as bad as I feared.
>
> Please see the attached patch.
>
> Thanks,
>  - Jon
>

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list