From 068fa4927e8bca10255224b9a4355f54edeceaf5 Mon Sep 17 00:00:00 2001 From: Anton Bachin Date: Thu, 21 Dec 2023 14:41:34 +0300 Subject: [PATCH] Rework the local docs build Make it possible to browse the assembled docs locally and use mostly relative links. --- Makefile | 43 +++++++++++++++++++------------------------ docs/conf.py | 2 +- docs/index.rst | 2 +- src/DNS.mli | 7 +++---- src/FS_event.mli | 7 +++---- src/TCP.mli | 6 +++--- src/UDP.mli | 6 +++--- src/async.mli | 5 ++--- src/buffer.mli | 4 +++- src/error.mli | 7 +++---- src/file.mli | 6 +++--- src/handle.mli | 6 +++--- src/idle.mli | 6 +++--- src/index.mld | 2 +- src/loop.mli | 6 +++--- src/mutex.mli | 5 ++--- src/pipe.mli | 8 ++++---- src/process.mli | 6 +++--- src/request.mli | 6 +++--- src/signal.mli | 6 +++--- src/stream.mli | 6 +++--- src/thread.mli | 4 ++-- src/thread_pool.mli | 7 +++---- src/timer.mli | 6 +++--- 24 files changed, 80 insertions(+), 89 deletions(-) diff --git a/Makefile b/Makefile index 8cdfdc17..48f5e34e 100644 --- a/Makefile +++ b/Makefile @@ -165,8 +165,14 @@ 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 : @@ -174,48 +180,37 @@ api-docs : .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 git@github.com: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 git@github.com: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) diff --git a/docs/conf.py b/docs/conf.py index a7ae3a8b..4ae63b80 100644 --- a/docs/conf.py +++ b/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') } diff --git a/docs/index.rst b/docs/index.rst index ab331290..24fdde19 100644 --- a/docs/index.rst +++ b/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 diff --git a/src/DNS.mli b/src/DNS.mli index 6c916e66..313cf16c 100644 --- a/src/DNS.mli +++ b/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, diff --git a/src/FS_event.mli b/src/FS_event.mli index c7c738c1..213b7f20 100644 --- a/src/FS_event.mli +++ b/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} diff --git a/src/TCP.mli b/src/TCP.mli index 61d27eec..6acfd3aa 100644 --- a/src/TCP.mli +++ b/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]}. diff --git a/src/UDP.mli b/src/UDP.mli index f5bef9bb..ff71a626 100644 --- a/src/UDP.mli +++ b/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]}. diff --git a/src/async.mli b/src/async.mli index 2ec3f4de..26d224de 100644 --- a/src/async.mli +++ b/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. *) diff --git a/src/buffer.mli b/src/buffer.mli index c1181f9e..f7f27031 100644 --- a/src/buffer.mli +++ b/src/buffer.mli @@ -3,7 +3,9 @@ -(** Data buffers. *) +(** Data buffers. + + See {{:../../../basics.html#buffers} {i Buffers}} in the user guide. *) diff --git a/src/error.mli b/src/error.mli index 0e6c318d..6672ac46 100644 --- a/src/error.mli +++ b/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 diff --git a/src/file.mli b/src/file.mli index 3cb0ee22..8c13d150 100644 --- a/src/file.mli +++ b/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, diff --git a/src/handle.mli b/src/handle.mli index 412e2e0f..55dcf061 100644 --- a/src/handle.mli +++ b/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 diff --git a/src/idle.mli b/src/idle.mli index 0e879506..89397c9c 100644 --- a/src/idle.mli +++ b/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]}. diff --git a/src/index.mld b/src/index.mld index 5ba1ba1b..55c928a5 100644 --- a/src/index.mld +++ b/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. diff --git a/src/loop.mli b/src/loop.mli index 7c2133fb..36fe2c51 100644 --- a/src/loop.mli +++ b/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} diff --git a/src/mutex.mli b/src/mutex.mli index eea7192a..851c549d 100644 --- a/src/mutex.mli +++ b/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. *) diff --git a/src/pipe.mli b/src/pipe.mli index 2d3dd206..a83ef2ef 100644 --- a/src/pipe.mli +++ b/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]}. diff --git a/src/process.mli b/src/process.mli index 48d4d663..023c6717 100644 --- a/src/process.mli +++ b/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} diff --git a/src/request.mli b/src/request.mli index 15ef2dd4..1be4cd09 100644 --- a/src/request.mli +++ b/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 diff --git a/src/signal.mli b/src/signal.mli index 357af330..08cda857 100644 --- a/src/signal.mli +++ b/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. *) diff --git a/src/stream.mli b/src/stream.mli index 9844a5c0..a9f409b1 100644 --- a/src/stream.mli +++ b/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}. diff --git a/src/thread.mli b/src/thread.mli index 0959e5aa..395ea724 100644 --- a/src/thread.mli +++ b/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 diff --git a/src/thread_pool.mli b/src/thread_pool.mli index 5de1f4aa..848efee6 100644 --- a/src/thread_pool.mli +++ b/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} diff --git a/src/timer.mli b/src/timer.mli index 175722c8..b1b3f735 100644 --- a/src/timer.mli +++ b/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}