[jit] Update the docs

On Wed, 2014-10-15 at 14:44 -0600, Jeff Law wrote:
> On 10/15/14 10:56, David Malcolm wrote:
> > On Tue, 2014-10-14 at 11:09 -0400, David Malcolm wrote:
> >> On Mon, 2014-10-13 at 13:45 -0400, David Malcolm wrote:
> >>> I'd like to merge the JIT branch into trunk:
> >>>    https://gcc.gnu.org/wiki/JIT
> >>>
> >>> This is "v2" since it incorporates fixes for the various issues
> >>> identified by Joseph in an earlier submission:
> >>>    https://gcc.gnu.org/ml/gcc-patches/2014-09/msg02056.html
> >>>
> >>> I've split up the current diff between trunk and the branch into 5
> >>> areas for ease of review (and to allow for early merger of the
> >>> supporting work, if it's deemed ready):
> >>>
> >>> patch 1: exposes an entrypoint in libiberty that I need
> >>> patch 2: configure and Makefile changes in "gcc"
> >>> patch 3: timevar.h: Add an auto_timevar class
> >>> patch 4: State cleanups in "gcc"
> >>> patch 5: Add the "jit" code itself
> >>>
> >>> [this is a diff of trunk r215958 aka
> >>> e012cdc775868e9922f5fef9068a764546876d93 which is from 2014-10-06,
> >>> vs jit branch version 75b3ee7acdc6de55354d65bb7d619386463e50a1].
> >>>
> >>> I've successfully bootstrapped and regression-tested the cumulative
> >>> result of all of the patches against a control build, building them
> >>> both with --enable-host-shared, and with
> >>>    --enable-languages=c,c++,objc,obj-c++,java,fortran,ada,go,lto
> >>> adding ",jit" to the test build (both on x86_64-unknown-linux-gnu;
> >>> Fedora 20).
> >>>
> >>> There were no regressions vs the control build, and the patched build
> >>> gains a jit.sum, with 4663 passes (and no failures).
> >>>
> >>> OK for trunk?
> >>
> >> Patch 5 seems to have been too large, even compressed, so I'm breaking
> >> it up into separate pieces and compressing, giving 10 patches in total
> >>
> >> Patches 1-4 are as above.
> >>
> >> Patch 5: remaining JIT-related changes outside of the gcc/jit/ subdir
> >>
> >> Patch 6: the core of the JIT implementation: the gcc/jit subdir
> >>
> >> Patch 7: the testsuite: gcc/testsuite/jit.dg
> >>
> >> Patch 8: sphinx-based documentation: the gcc/jit/docs subdir
> >>
> >> Patch 9: texinfo documentation autogenerated from the sphinx sources.
> >>
> >> Patch 10: the ChangeLog.jit logs from the branch.
> >
> > For some reason, patches 8 and 9 don't seem to have made it through to
> > the list, even after a couple of attempts.
> >
> > Here's the ChangeLog for patch 8:
> >
> > gcc/jit/ChangeLog:
> >
> >          * docs/Makefile: New.
> >          * docs/conf.py: New.
> >          * docs/examples/install-hello-world.c: New.
> >          * docs/examples/tut01-square.c: New.
> >          * docs/examples/tut02-sum-of-squares.c: New.
> >          * docs/examples/tut03-toyvm/Makefile: New.
> >          * docs/examples/tut03-toyvm/factorial.toy: New.
> >          * docs/examples/tut03-toyvm/fibonacci.toy: New.
> >          * docs/examples/tut03-toyvm/toyvm.c: New.
> >          * docs/index.rst: New.
> >          * docs/internals/index.rst: New.
> >          * docs/intro/factorial.png: New.
> >          * docs/intro/index.rst: New.
> >          * docs/intro/install.rst: New.
> >          * docs/intro/sum-of-squares.png: New.
> >          * docs/intro/tutorial01.rst: New.
> >          * docs/intro/tutorial02.rst: New.
> >          * docs/intro/tutorial03.rst: New.
> >          * docs/topics/contexts.rst: New.
> >          * docs/topics/expressions.rst: New.
> >          * docs/topics/functions.rst: New.
> >          * docs/topics/index.rst: New.
> >          * docs/topics/locations.rst: New.
> >          * docs/topics/objects.rst: New.
> >          * docs/topics/results.rst: New.
> >          * docs/topics/types.rst: New.
> >
> > The new files can be seen at:
> > https://gcc.gnu.org/git/?p=gcc.git;a=tree;f=gcc/jit/docs;h=a31ffa5d5068f088a314bad3f904887f6dfa3098
> >
> > HTML built from these (via sphinx) can be seen at:
> > https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/index.html
> So I'm reading this and the first thing that comes to mind is *way* too 
> much on installation via packages.  That documentation may be 
> appropriate elsewhere, but I don't think it makes sense in GCC.

I've moved all info on installation via packages to the wiki.

> As far as installation from source, assuming the bits are integrated 
> onto the trunk, this section should be dramatically simplified and in 
> fact ought to be removed.

I've eliminated much of this, moving what remains to the final page of
the docs, which is aimed at contributors (and, in particular, myself).

> For the examples, assume folks have built from source and installed into 
> whatever prefix they selected.  ie, I thik that section becomes
> 
> gcc jit-hello-world.c -o jit-hello-world -lgccjit
> 
> All the other stuff is unwanted/unneeded.  No need to talk about running 
> from different prefixes, locally built trees.  Remove the pkg-config 
> stuff, that's not a way we do things in the gcc-world.  If you want to 
> make an argument for pkg-config, then that's independent of this work 
> and should be made pervasive in GCC if we were to decide to go that 
> route.  Having it just for the plugin is inconsistent and confusing.

I'll make that argument another time.  For now, I've removed it for the
sake of getting the code into trunk.  In the patch below I've removed
mentions of it from the docs.

> Similarly for the stuff for how to use a working copy without 
> installing.  Might be useful to document somewhere, but for GCC, we 
> expect folks to build & install.   Running the testsuite should just be 
> make check, which is no different than other parts of GCC

I've updated the testsuite to no longer need an install, so I've updated
the final page of the docs to reflect that.

> and I don't  think you need a page on how to do that.

Sadly, *I* do need such a page :)

This may turn into a rant; sorry...

IIRC, it took me several hours way back when to figure out how to just
run one specific testcase (as opposed to the whole suite), and I can
never remember the right incantation, so I wrote it up on the wiki page,
and now just go there when I find myself wondering the right incantation.
I can never find things in the .texi files or the HTML built from them.

So right now there *is* a page that I use to tell me how to do that, but
it's on the wiki...

Having vital documentation live on a *wiki* disturbs me.

There's an excellent talk from Jacob Kaplan-Moss:
"Writing Great Documentation" (PyCon Atlanta 2011):
  https://www.youtube.com/watch?v=z3fRu9pkuXE
with the quote:
  "a wiki is where good documentation goes to die"

I recommend watching the whole talk (e.g. for the material about how
good documentation is fractal in nature [1]).

I have a pet theory that any time that I have to use a wiki can be
seen as a symptom of dysfunction in a project - why am I editing a
wiki, rather that a file in a source tree?  Some of the reasons might
be (not singling out gcc here):
* a project has chosen an overly cumbersome source representation for
  its docs, and is using a wiki to avoid e.g. having to type DocBook
  (I speak as a reformed former DocBook enthusiast).
* a project doesn't have a good place to put said documentation (e.g. we
  have a user manual and an installation manual; do we have a contributor
  manual?  Though why make such distinctions?  Maybe we can build a
  smoother on-ramp for turning users into contributors?)
...etc

So I need somewhere to put this documentation, and I'd rather take the
best parts of the wiki page and put them in a contributor guide.  Given
that this is Sphinx-based, there's already a degree of separation
between these docs and the existing GCC docs - this isn't going to
be a part of the GCC manual at this time, it's going to be a sibling
document.  Hence I think it's reasonable for this guide to cover both
users of *and* contributors to the JIT library, with the
contributor-focussed content isolated from the user-focussed content
as a appendix.

There's also what I call the "man page disease", where documentation
is written as if only saying anything once is a virtue.  I believe
most developers only read small parts of documentation based on skimming
and on the pages they see in internet search results, hence I believe
redundancy is a virtue: it's OK to repeat ourselves, to restate things
with examples for clarity.  This may be a generation-gap thing.

A use-case for the contributor-focussed content is for things like
"I'm debugging a local build of GNU Octave, running against a local
(not-installed) build of libgccjit, and need to make a one-line change
to libgccjit.  What exactly needs to be set in the environment when
invoking gdb?"  It's painful figuring this out by hand, and it needs
to be captured in the docs somewhere.

OK, rant over :)

> So I think the general comment is assume the normal build/install 
> scenario, removing all the stuff that becomes extraneous.  Assume your 
> target audience isn't hacking GCC itself and simplify appropriately.
> 
> If you want to pull those developer-oriented docs somewhere on the GCC 
> web site, I think we can find a way to make that happen, but I don't 
> think all that stuf needs to be in the GCC manual.

The following patch:

  * eliminates all mentions of pkg-config

  * eliminates the installation section and the discussion of packages

  * converts the final page (docs/internals/index.rst) into a short
    guide for contributors to the project.  I think having it next
    to the rest of the docs is reasonable.

I've committed it to the dmalcolm/jit branch, and prebuilt HTML can be seen
at:
  https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/index.html
as before.  The significant changes can be seen on the first page of the
tutorial:
  https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/intro/tutorial01.html
and in the final page of the docs:
  https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/internals/index.html
which as I said above is a compendium of contributor docs, of which
I'm the primary consumer.

Is this more acceptable?

After this patch, the "intro/install.rst" becomes a poor name.  I've
renamed it in a followup patch to "intro/tutorial01.rst".

[1] 21 minutes in fwiw, but really, watch it all, it's a great talk.

Committed to branch dmalcolm/jit:

gcc/jit/ChangeLog.jit:
	* docs/intro/install.rst ("Installation via packages"): Drop
	this section.
	("Installation from source"): Drop this section, moving parts
	of it to https://gcc.gnu.org/wiki/JIT and some others to
	docs/internals/index.rst.
	("Hello world"): This section becomes the only remaining part
	of this file.  Eliminate references to pkg-config.

	* docs/internals/index.rst
	("Using a working copy without installing every time"): Rewrite
	as...
	("Working on the JIT library"): ...new section, aimed at
	contributors (and myself) working from a build directory,
	eliminating references to installation.  Add description
	of pertinent configuration options.
	("Running the test suite"): Add setting of LIBRARY_PATH to
	description of how to run a built binary outside of the test
	suite.
	("Environment variables"): New section, describing pertinent
	environment variables.
---
 gcc/jit/ChangeLog.jit            |  23 +++++
 gcc/jit/docs/internals/index.rst | 133 +++++++++++++++++++-------
 gcc/jit/docs/intro/install.rst   | 201 +++------------------------------------
 3 files changed, 132 insertions(+), 225 deletions(-)

[jit] Update the docs

Commit Message

Patch