SQLite Forum

Generating documentation
Login

Generating documentation

(1) By James K. Lowden (jklowden) on 2020-05-20 19:43:40 [link] [source]

I don't understand the directions for how to generate the documentation.

Whether I use fossil, or pull the snapshot, my procedure is to create a build directory, cd to it, and run ../configure && make. In neither case do I get a docs directory, as indicated on the documentation source page.

The instructions say,

Download and unpack the source trees for SQLite

Does that mean I cannot use the fossil repo? (I guess so, since the documentation system is in its own repository, which afaict cannot be cloned.)

The SQLite install should be in ../sqlite

Is that literally true? The parent of the build directory must be "sqlite"? Or the prefix must be "../sqlite"?

Edit the Makefile for your system

[Emphasis mine.] The Makefile means the one generated by configure? If so, I see no reference to TCLINC and TCLFLAGS, nor to a docs directory in configure.ac or Makefile.in.

Finally, step b. at the end says,

Set TH3= and SLT= to empty strings

Those variables also do not appear anywhere that I see.

BTW, the comments in Makefile.in say See the comment at the beginning of configure.in for additional information. I think that should be configure.ac these days.

Many thanks.

(2) By Richard Hipp (drh) on 2020-05-20 19:53:45 in reply to 1 [link] [source]

Building the documentation requires that you download the canonical source tree for both SQLite and the "DocSrc". You can do this as tarballs, but you will probably want to use Fossil.

The canonical source code is different from the "snapshot". The snapshots are preprocessed sources that are easier to compile. We make snapshots available so that people who just what SQLite can get to it easily. Building the documentation is more involved. As far as I know, the documentation builds only work on Linux.

Pay not attention to the "snapshots". Nor should you mess with any GitHub mirrors. You want to clone these two Fossil repositories:

(3) By Warren Young (wyoung) on 2020-05-20 20:30:36 in reply to 1 [source]

Does that mean I cannot use the fossil repo?

No; "opening" the SQLite Fossil repo counts as "unpacking the source tree for SQLite."

The main thing you cannot use is the amalgamation version. It's missing pieces relative to the full tree, needed for building the docs.

Another source tree that should work for this is the "snapshot" zip file.

the documentation system is in its own repository, which afaict cannot be cloned

Works for me:

$ fossil clone https://sqlite.org/docsrc/ sqlite-docsrc.fossil
Round-trips: 3   Artifacts sent: 0  received: 10182
Clone done, sent: 768  received: 15275104  ip: 1.2.3.4
Rebuilding repository meta-data...
  100.0% complete...
Extra delta compression... 
Vacuuming the database... 
project-id: a49a74a282acfe2f07de91768b854dffd3d783df
...etc...

The parent of the build directory must be "sqlite"?

No. It's saying that there must be a peer to the current directory called "sqlite". A cd ../sqlite command relative to the top of the docsrc repo must put you at the root of the SQLite source tree.

The Makefile means the one generated by configure?

No, it means the one at the root of the docsrc repo.

Those variables also do not appear anywhere that I see.

They're in the docsrc Makefile.

(4) By James K. Lowden (jklowden) on 2020-05-20 21:20:50 in reply to 3 [link] [source]

Thanks, Warren, that's very helpful. I fetched the sources and added a symlink for ../sqlite.

My mistake was apparently to follow the www2 link. Some reptilian part of my gopher brain (to mix metaphors) said, hey, Newark is closer than Dallas.

$ fossil clone http://www2.sqlite.org/cgi/docsrc sqlite-doc.fossil
Round-trips: 2   Artifacts sent: 0  received: 0
Error: not authorized to clone
Round-trips: 2   Artifacts sent: 0  received: 0
Clone done, sent: 548  received: 562  ip: 66.228.42.154
server returned an error - clone aborted

All the bits seem to be where they belong now. :-)