Rework the local docs build

Make it possible to browse the assembled docs locally and use mostly
relative links.

Makefile

@@ -165,57 +165,52 @@ check-ejected-build :
 install-autotools :
 	sudo apt install automake libtool
 
+DOCS := docs/_build
+
 .PHONY : docs
-docs : api-docs luvbook
+docs : luvbook api-docs
+	mkdir -p $(DOCS)
+	cp -r _build/default/_doc/_html/luv $(DOCS)
+	cp -r _build/default/_doc/_html/odoc.support $(DOCS)
+	@echo See $(DOCS)/index.html
 
 .PHONY : api-docs
 api-docs :
 	dune build @doc -p luv
 
 .PHONY : luvbook
 luvbook :
-	sphinx-build -b html docs docs/_build
+	sphinx-build -b html docs $(DOCS)
 
 .PHONY : watch-api-docs
 watch-api-docs : api-docs
 	inotifywait -mr -e modify --format '%f' src \
-	  | xargs -L1 -I X make api-docs
+	  | xargs -L1 -I X make docs
 
 .PHONY : watch-luvbook
 watch-luvbook : luvbook
 	inotifywait -mr -e modify docs/conf.py docs/*.rst example \
-	  | xargs -L1 -I X make luvbook
+	  | xargs -L1 -I X make docs
 
 .PHONY : install-sphinx
 install-sphinx :
 	sudo apt install python3-pip
 	pip3 install -U sphinx
 
-# make watch-api-docs &
-# make watch-luvbook &
-# open _build/default/_doc/_html/index.html
-# open docs/_build/index.html
-
-DOCS := ../gh-pages
+PAGES := ../gh-pages
 
 .PHONY : stage-docs
-stage-docs : api-docs luvbook
-	[ -d $(DOCS) ] || git clone [email protected]:aantron/luv.git $(DOCS)
-	cd $(DOCS) && git checkout gh-pages
-	rm -rf $(DOCS)/*
-	cp -r _build/default/_doc/_html/* $(DOCS)
-	cp -r docs/_build/* $(DOCS)
-	cd $(DOCS) && mv _static static
-	cd $(DOCS) && mv _sources sources
-	cd $(DOCS) && mv _odoc_support odoc_support
-	cd $(DOCS) && ls *.html | xargs -L1 sed -i 's#_static/#static/#g'
-	cd $(DOCS) && ls *.html | xargs -L1 sed -i 's#_sources/#sources/#g'
-	cd $(DOCS) && find -name '*.html' | xargs -L1 sed -i 's#_odoc_support/#odoc_support/#g'
-	cd $(DOCS) && git add -A && git commit --amend --no-edit --reset-author
+stage-docs : docs
+	[ -d $(PAGES) ] || git clone [email protected]:aantron/luv.git $(PAGES)
+	cd $(PAGES) && git checkout gh-pages
+	rm -rf $(PAGES)/*
+	cp -r $(DOCS)/* $(PAGES)
+	touch $(PAGES)/.nojekyll
+	cd $(PAGES) && git add -A && git commit --amend --no-edit --reset-author
 
 .PHONY : publish-docs
 publish-docs : stage-docs
-	cd $(DOCS) && git push --force-with-lease
+	cd $(PAGES) && git push --force-with-lease
 
 VERSION := $(shell git describe --abbrev=0)
 RELEASE := luv-$(VERSION)

docs/conf.py

@@ -32,7 +32,7 @@
 extensions = ['sphinx.ext.extlinks']
 
 extlinks = {
-    'api': ('https://aantron.github.io/luv/luv/Luv/%s', '%s'),
+    'api': ('luv/Luv/%s', '%s'),
     'example': ('https://github.com/aantron/luv/blob/master/example/%s', '%s'),
     'man': ('http://man7.org/linux/man-pages/man%s.html', '%s')
 }

docs/index.rst

@@ -14,7 +14,7 @@ See also:
 .. _Luv: https://github.com/aantron/luv
 .. _Project page: https://github.com/aantron/luv
 .. _libuv: https://github.com/libuv/libuv
-.. _API reference: https://aantron.github.io/luv/luv/index.html#api-reference
+.. _API reference: luv/index.html#api-reference
 .. _libuv manual: http://docs.libuv.org/en/v1.x/
 
 .. rubric:: Table of contents

src/DNS.mli

@@ -5,10 +5,9 @@
 
 (** DNS queries.
 
-    See {{:https://aantron.github.io/luv/networking.html#querying-dns} {i
-    Querying DNS}} in the user guide and
-    {{:http://docs.libuv.org/en/v1.x/dns.html} {i DNS utility functions}} in
-    libuv.
+    See {{:../../../networking.html#querying-dns} {i Querying DNS}} in the user
+    guide and {{:http://docs.libuv.org/en/v1.x/dns.html} {i DNS utility
+    functions}} in libuv.
 
     This module exposes two main functions, {!Luv.DNS.getaddrinfo} and
     {!Luv.DNS.getnameinfo}. Both take an optional request object. By default,

src/FS_event.mli

@@ -5,10 +5,9 @@
 
 (** Filesystem events.
 
-    See {{:https://aantron.github.io/luv/filesystem.html#file-change-events} {i
-    File change events}} in the user guide and
-    {{:http://docs.libuv.org/en/v1.x/fs_event.html} [uv_fs_event_t] {i — FS
-    Event handle}} in libuv. *)
+    See {{:../../../filesystem.html#file-change-events} {i File change events}}
+    in the user guide and {{:http://docs.libuv.org/en/v1.x/fs_event.html}
+    [uv_fs_event_t] {i — FS Event handle}} in libuv. *)
 
 type t = [ `FS_event ] Handle.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/fs_event.html#c.uv_fs_event_t}

src/TCP.mli

@@ -5,9 +5,9 @@
 
 (** TCP sockets.
 
-    See {{:https://aantron.github.io/luv/networking.html#tcp} {i TCP}} in the
-    user guide and {{:http://docs.libuv.org/en/v1.x/tcp.html} [uv_tcp_t] {i —
-    TCP handle}} in libuv. *)
+    See {{:../../../networking.html#tcp} {i TCP}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/tcp.html} [uv_tcp_t] {i — TCP handle}} in
+    libuv. *)
 
 type t = [ `TCP ] Stream.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/tcp.html#c.uv_tcp_t} [uv_tcp_t]}.

src/UDP.mli

@@ -5,9 +5,9 @@
 
 (** UDP sockets.
 
-    See {{:https://aantron.github.io/luv/networking.html#udp} {i UDP}} in the
-    user guide and {{:http://docs.libuv.org/en/v1.x/udp.html} [uv_udp_t] {i —
-    UDP handle}} in libuv. *)
+    See {{:../../../networking.html#udp} {i UDP}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/udp.html} [uv_udp_t] {i — UDP handle}} in
+    libuv. *)
 
 type t = [ `UDP ] Handle.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/udp.html#c.uv_udp_t} [uv_udp_t]}.

src/async.mli

@@ -5,9 +5,8 @@
 
 (** Inter-loop communication.
 
-    See
-    {{:https://aantron.github.io/luv/threads.html#inter-thread-communication} {i
-    Inter-thread communication}} in the user guide and
+    See {{:../../../threads.html#inter-thread-communication} {i Inter-thread
+    communication}} in the user guide and
     {{:http://docs.libuv.org/en/v1.x/async.html} [uv_async_t] {i — Async
     handle}} in libuv. *)
 

src/buffer.mli

@@ -3,7 +3,9 @@
 
 
 
-(** Data buffers. *)
+(** Data buffers.
+
+    See {{:../../../basics.html#buffers} {i Buffers}} in the user guide. *)
 
 
 

src/error.mli

@@ -5,10 +5,9 @@
 
 (** Error handling.
 
-    See {{:https://aantron.github.io/luv/basics.html#error-handling} {i Error
-    handling}} in the user guide and
-    {{:http://docs.libuv.org/en/v1.x/errors.html} {i Error handling}} in
-    libuv. *)
+    See {{:../../../basics.html#error-handling} {i Error handling}} in the user
+    guide and {{:http://docs.libuv.org/en/v1.x/errors.html} {i Error handling}}
+    in libuv. *)
 
 type t = [
   | `E2BIG

src/file.mli

@@ -5,9 +5,9 @@
 
 (** File operations.
 
-    See {{:https://aantron.github.io/luv/filesystem.html} {i Filesystem}} in the
-    user guide and  {{:http://docs.libuv.org/en/v1.x/fs.html} {i File system
-    operations}} in libuv.
+    See {{:../../../filesystem.html} {i Filesystem}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/fs.html} {i File system operations}} in
+    libuv.
 
     This module exposes all the filesystem operations of libuv with an
     asynchronous (callback) interface. There is an additional submodule,

src/handle.mli

@@ -5,9 +5,9 @@
 
 (** Handles.
 
-    See {{:https://aantron.github.io/luv/basics.html#handles} {i Handles}} in
-    the user guide and  {{:http://docs.libuv.org/en/v1.x/handle.html}
-    [uv_handle_t] — {i Base handle}} in libuv.
+    See {{:../../../basics.html#handles} {i Handles}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/handle.html} [uv_handle_t] — {i Base
+    handle}} in libuv.
 
     In libuv, [uv_handle_t] is a sort of “abstract” base type that supports
     functions common to all handles. All concrete handles are of more specific

src/idle.mli

@@ -5,9 +5,9 @@
 
 (** Per-iteration callback.
 
-    See {{:https://aantron.github.io/luv/basics.html#example} {i Example}} in
-    the user guide and {{:http://docs.libuv.org/en/v1.x/idle.html} [uv_idle_t]
-    {i — Idle handle}} in libuv. *)
+    See {{:../../../basics.html#example} {i Example}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/idle.html} [uv_idle_t] {i — Idle handle}}
+    in libuv. *)
 
 type t = [ `Idle ] Handle.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/idle.html#c.uv_idle_t} [uv_idle_t]}.

src/index.mld

@@ -31,7 +31,7 @@ This is the auto-generated API reference. For more conceptual information and
 examples, see:
 
 - {{:https://github.com/aantron/luv} Project page}
-- {{:https://aantron.github.io/luv/} User guide}
+- {{:../index.html} User guide}
 - {{:https://github.com/aantron/luv/tree/master/example} Examples}, which are
 presented in the user guide.
 

src/loop.mli

@@ -5,9 +5,9 @@
 
 (** Event loops.
 
-    See {{:https://aantron.github.io/luv/basics.html#event-loops} {i Event
-    loops}} in the user guide and {{:http://docs.libuv.org/en/v1.x/loop.html}
-    [uv_loop_t] — {i Event loop}} in libuv. *)
+    See {{:../../../basics.html#event-loops} {i Event loops}} in the user guide
+    and {{:http://docs.libuv.org/en/v1.x/loop.html} [uv_loop_t] — {i Event
+    loop}} in libuv. *)
 
 type t = C.Types.Loop.t Ctypes.ptr
 (** Binds {{:http://docs.libuv.org/en/v1.x/loop.html#c.uv_loop_t}

src/mutex.mli

@@ -5,9 +5,8 @@
 
 (** Mutexes.
 
-    See
-    {{:https://aantron.github.io/luv/threads.html#synchronization-primitives} {i
-    Synchronization primitives}} in the user guide and
+    See {{:../../../threads.html#synchronization-primitives} {i Synchronization
+    primitives}} in the user guide and
     {{:http://docs.libuv.org/en/v1.x/threading.html#mutex-locks} {i Mutex
     locks}} in libuv. *)
 

src/pipe.mli

@@ -5,10 +5,10 @@
 
 (** Pipes.
 
-    See {{:https://aantron.github.io/luv/processes.html#child-process-i-o} {i
-    Child process I/O}} and {{:https://aantron.github.io/luv/processes.html#ipc}
-    {i IPC}} in the user guide, and {{:http://docs.libuv.org/en/v1.x/pipe.html}
-    [uv_pipe_t] {i — Pipe handle}} in libuv. *)
+    See {{:../../../processes.html#child-process-i-o} {i Child process I/O}} and
+    {{:../../../processes.html#ipc} {i IPC}} in the user guide, and
+    {{:http://docs.libuv.org/en/v1.x/pipe.html} [uv_pipe_t] {i — Pipe handle}}
+    in libuv. *)
 
 type t = [ `Pipe ] Stream.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/pipe.html#c.uv_pipe_t} [uv_pipe_t]}.

src/process.mli

@@ -5,9 +5,9 @@
 
 (** Subprocesses.
 
-    See {{:https://aantron.github.io/luv/processes.html} {i Processes}} in the
-    user guide and {{:http://docs.libuv.org/en/v1.x/process.html} [uv_process_t]
-    {i — Process handle}} in libuv. *)
+    See {{:../../../processes.html} {i Processes}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/process.html} [uv_process_t] {i — Process
+    handle}} in libuv. *)
 
 type t = [ `Process ] Handle.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/process.html#c.uv_process_t}

src/request.mli

@@ -5,9 +5,9 @@
 
 (** Requests.
 
-    See {{:https://aantron.github.io/luv/basics.html#requests} {i Requests}} in
-    the user guide and {{:http://docs.libuv.org/en/v1.x/request.html} [uv_req_t]
-    — {i Base request}} in libuv.
+    See {{:../../../basics.html#requests} {i Requests}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/request.html} [uv_req_t] — {i Base
+    request}} in libuv.
 
     Requests are objects libuv uses to track asynchronous operations, and
     sometimes to communicate their results. For the most part Luv handles

src/signal.mli

@@ -5,9 +5,9 @@
 
 (** Signals.
 
-    See {{:https://aantron.github.io/luv/processes.html#signals} {i Signals}} in
-    the user guide and {{:http://docs.libuv.org/en/v1.x/signal.html}
-    [uv_signal_t] {i — Signal handle}} in libuv. *)
+    See {{:../../../processes.html#signals} {i Signals}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/signal.html} [uv_signal_t] {i — Signal
+    handle}} in libuv. *)
 
 
 

src/stream.mli

@@ -5,9 +5,9 @@
 
 (** Streams.
 
-    See {{:https://aantron.github.io/luv/networking.html#tcp} {i TCP}} in the
-    user guide and {{:http://docs.libuv.org/en/v1.x/stream.html} [uv_stream_t]
-    {i — Stream handle}} in libuv.
+    See {{:../../../networking.html#tcp} {i TCP}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/stream.html} [uv_stream_t] {i — Stream
+    handle}} in libuv.
 
     Several types of {{!Luv.Handle.t} handle} have a portion of their interface
     in common, which portion is abstracted out into this module {!Luv.Stream}.

src/thread.mli

@@ -5,8 +5,8 @@
 
 (** Threads.
 
-    See {{:https://aantron.github.io/luv/threads.html} {i Threads}} in the user
-    guide and {{:http://docs.libuv.org/en/v1.x/threading.html} {i Threading and
+    See {{:../../../threads.html} {i Threads}} in the user guide and
+    {{:http://docs.libuv.org/en/v1.x/threading.html} {i Threading and
     synchronization utilities}} in libuv. *)
 
 type t

src/thread_pool.mli

@@ -5,10 +5,9 @@
 
 (** Thread pool.
 
-    See {{:https://aantron.github.io/luv/threads.html#libuv-thread-pool} {i
-    libuv thread pool}} in the user guide and
-    {{:http://docs.libuv.org/en/v1.x/threadpool.html} {i Thread pool work
-    scheduling}} in libuv. *)
+    See {{:../../../threads.html#libuv-thread-pool} {i libuv thread pool}} in
+    the user guide and {{:http://docs.libuv.org/en/v1.x/threadpool.html} {i
+    Thread pool work scheduling}} in libuv. *)
 
 (** Optional request objects for canceling thread pool requests. Binds
     {{:http://docs.libuv.org/en/v1.x/threadpool.html#c.uv_work_t}

src/timer.mli

@@ -5,9 +5,9 @@
 
 (** Timers.
 
-    See {{:https://aantron.github.io/luv/basics.html#hello-world} {i Hello,
-    world!}} in the user guide and {{:http://docs.libuv.org/en/v1.x/timer.html}
-    [uv_timer_t] {i — Timer handle}} in libuv. *)
+    See {{:../../../basics.html#hello-world} {i Hello, world!}} in the user
+    guide and {{:http://docs.libuv.org/en/v1.x/timer.html} [uv_timer_t] {i —
+    Timer handle}} in libuv. *)
 
 type t = [ `Timer ] Handle.t
 (** Binds {{:http://docs.libuv.org/en/v1.x/timer.html#c.uv_timer_t}