Re: monoapi Documentation

--=-n6xhV6PcYkB7lldTSj9h
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

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


--=-n6xhV6PcYkB7lldTSj9h
Content-Disposition: attachment; filename=mono-docs.patch
Content-Type: text/x-patch; name=mono-docs.patch; charset=utf-8
Content-Transfer-Encoding: 7bit

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 116512)
+++ ChangeLog	(working copy)
@@ -1,3 +1,8 @@
+2008-10-29  Jonathan Pryor  <[email protected]>
+
+	* Makefile.am: Build `docs` after `runtime`, so that it can depend
+	  upon mdoc.exe for it's operation.
+
 2008-10-20  Jonathan Pryor  <[email protected]>
 
 	* 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 @@
+2008-10-29  Jonathan Pryor  <[email protected]>
+
+	* . (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  <[email protected]>
 
 	* 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


--=-n6xhV6PcYkB7lldTSj9h
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
Mono-docs-list maillist  -  [email protected]
http://lists.ximian.com/mailman/listinfo/mono-docs-list

--=-n6xhV6PcYkB7lldTSj9h--