Add seaborg+docsify for Markdown doc generation

.gitignore

@@ -1,2 +1,5 @@
 .vscode
 build
+node_modules
+docs/internal
+docs/public

Doxyfile_internal

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.6
+# Doxyfile 1.8.20
 
 @INCLUDE = Doxyfile_common
 
@@ -7,7 +7,7 @@
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/internal
+OUTPUT_DIRECTORY       = docs/internal
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class will
 # be included in the documentation.
@@ -37,13 +37,6 @@ ENABLED_SECTIONS       = PRIVATE
 
 SOURCE_BROWSER         = YES
 
-# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
-# special comment blocks from generated source code fragments. Normal C, C++ and
-# Fortran comments will always remain visible.
-# The default value is: YES.
-
-STRIP_CODE_COMMENTS    = NO
-
 # If the REFERENCED_BY_RELATION tag is set to YES then for each documented
 # function all documented functions referencing it will be listed.
 # The default value is: NO.

Doxyfile_public

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.6
+# Doxyfile 1.8.20
 
 @INCLUDE = Doxyfile_common
 
@@ -7,7 +7,7 @@
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/public
+OUTPUT_DIRECTORY       = docs/public
 
 # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
 # undocumented members inside documented classes or files. If set to NO these
@@ -50,13 +50,6 @@ SHOW_USED_FILES        = NO
 
 SHOW_FILES             = NO
 
-# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
-# special comment blocks from generated source code fragments. Normal C, C++ and
-# Fortran comments will always remain visible.
-# The default value is: YES.
-
-STRIP_CODE_COMMENTS    = NO
-
 # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a
 # verbatim copy of the header file for each class for which an include is
 # specified. Set to NO to disable this.

README.md

@@ -10,18 +10,18 @@ language. It features:
 
 Colibri is written in plain C and is free of any dependency besides system
 libraries. The compiled binary DLL on Windows is about 85kB. The source code is
-heavily commented using the [Doxygen](http://www.doxygen.nl/) syntax.
+heavily commented using the [Doxygen] syntax.
 
 ## License
 
-Colibri is released under the terms of the The 3-Clause BSD License:
+Colibri is released under the terms of the 3-Clause BSD License:
 
 https://opensource.org/licenses/BSD-3-Clause
 
 ## History
 
 I began working on Colibri around 2008 while thinking about the future of the
-[Tcl](https://www.tcl-lang.org) language. Tcl is a string-based language on the
+[Tcl] language. Tcl is a string-based language on the
 outside, and although it uses more elaborate data types on the inside for
 performance, its string implementation still relies on flat arrays of
 characters. Colibri started as an experiment with ropes, a string data structure
@@ -39,6 +39,8 @@ length of about 5cm. They are renown for their stationary and backward flight
 abilities on par with flying insects, which allow them to feed on the nectar of
 plants and flowers in-flight.
 
+[![mellisuga_helenae]][mellisuga_helenae_link]
+
 I've chosen this name for this project because its goal is to be fast and
 lightweight, and also to follow the feather and bird theme shared with Tcl and
 many related projects.
@@ -58,16 +60,15 @@ word types:
   - Floating point numbers
   - Unicode Characters
 
-* Immutable Unicode strings:
+- Immutable Unicode strings:
 
   - Regular strings: flat arrays of characters using 1/2/4-byte fixed width or
     UTF-8/16 variable width encodings
-  - [Ropes](<https://en.wikipedia.org/wiki/Rope_(data_structure)>):
-    self-balancing binary trees of strings
+  - [Ropes]: self-balancing binary trees of strings
 
-* String buffers for efficient dynamic string building
+- String buffers for efficient dynamic string building
 
-* Linear collections:
+- Linear collections:
 
   - Immutable vectors: fixed-length, flat arrays of words
   - Mutable words: flat arrays of words with a preallocated capacity
@@ -76,23 +77,23 @@ word types:
     conversion to immutable form; large mutable lists can be sparsely allocated
   - Custom lists: collections implemented with custom code
 
-* Mutable associative arrays:
+- Mutable associative arrays:
 
   - Hash maps: randomized associative arrays with integer, string or custom keys
   - Trie maps: self-sorting associative arrays with integer, string or custom
     keys
   - Custom maps: associative arrays implemented with custom code
 
-* Custom word types: dynamic datatypes implemented with custom code, with all
+- Custom word types: dynamic datatypes implemented with custom code, with all
   the benefits of automatic memory management
 
 Strings, linear collections and associative arrays come with generic iterators.
 
 ### Word synonyms
 
-In [duck-typed](https://en.wikipedia.org/wiki/Duck_typing) languages like Tcl,
-the type of a value depends on the way it is used, which can vary over time. For
-example, the literal `123` can represent:
+In [duck-typed][duck-typing] languages like Tcl, the type of a value depends on
+the way it is used, which can vary over time. For example, the literal `123` can
+represent:
 
 - the string "123"
 - the integer 123, in its various binary forms (8, 16, 32 bits...)
@@ -102,14 +103,14 @@ example, the literal `123` can represent:
 
 High-level language implementations typically associate such values with an
 internal structure that represent the underlying type at a given time. This
-technique avoids repeated data conversions, a typically expensive operation,
-and hence gives a performance boost when a value is used repeatedly (in a
-loop for example). However, in some cases the type may alternate between two or
-more internal representations; for example the above string may switch several
-times between integer and float representations. In the Tcl world this
-phenomenon is known as "shimmering". In such occurrences, the previous internal
-representation is lost and will have to be computed again shall the value be
-used with the same apparent type later on.
+technique avoids repeated data conversions, a typically expensive operation, and
+hence gives a performance boost when a value is used repeatedly (in a loop for
+example). However, in some cases the type may alternate between two or more
+internal representations; for example the above string may switch several times
+between integer and float representations. In the Tcl world this phenomenon is
+known as "shimmering". In such occurrences, the previous internal representation
+is lost and will have to be computed again shall the value be used with the same
+apparent type later on.
 
 Shimmering happens when an external representation can only have one internal
 representation. However, in Colibri any word can have an arbitrary number of
@@ -125,10 +126,10 @@ avoid this class of problems altogether.
 
 Words are either immediate or allocated.
 
-Most primitives are represented as immediate values whenever possible: the
-value is stored directly in the pointer rather than in an allocated structure.
-In effect, this means that collections of such words need no extra
-storage space besides the collection itself.
+Most primitives are represented as immediate values whenever possible: the value
+is stored directly in the pointer rather than in an allocated structure. In
+effect, this means that collections of such words need no extra storage space
+besides the collection itself.
 
 Allocated words are stored in cells. Each cell is made of 4 machine words, i.e.
 16 bytes on 32-bit architectures, and 32 bytes on 64-bits. Predefined datatypes
@@ -150,11 +151,10 @@ copying, mark-and-sweep, garbage collector.
 
 #### Exact
 
-Contrary to conservative garbage collectors such as the
-[Boehm GC](https://en.wikipedia.org/wiki/Boehm_garbage_collector), an exact
-garbage collector doesn't rely on heuristics to know when and where to follow a
-pointer to reachable memory. This ensures that no memory will leak or be freed
-accidentally.
+Contrary to conservative garbage collectors such as the [Boehm GC][boehm-gc], an
+exact garbage collector doesn't rely on heuristics to know when and where to
+follow a pointer to reachable memory. This ensures that no memory will leak or
+be freed accidentally.
 
 Colibri words are designed with that goal in mind. All predefined word types are
 automatically garbage-collected. Custom types can define a finalizer that is
@@ -184,8 +184,8 @@ survive the next GC.
 In the general case, memory promotion is done by moving whole pages from older
 to newer memory pools. This minimizes CPU overhead but may lead to memory
 fragmentation over time. So when fragmentation exceeds a certain threshold,
-cells are instead moved to a new, compact page in the target pool. This
-improves locality of reference and cache use over time.
+cells are instead moved to a new, compact page in the target pool. This improves
+locality of reference and cache use over time.
 
 #### Mark-and-sweep
 
@@ -245,25 +245,24 @@ variables, and write barriers for change detection. At present both Windows and
 Unix (Linux) versions are provided, the latter using `mmap`. Porting to other
 systems should require minimal effort as long as they provide the necessary
 features; the platform-specific code is limited to a handful of functions
-gathered in dedicated source subtrees. Platform-specific peculiarities
-should not impact the overall architecture. Indeed, Windows and Unix platforms
-are different enough to be confident on this point.
+gathered in dedicated source subtrees. Platform-specific peculiarities should
+not impact the overall architecture. Indeed, Windows and Unix platforms are
+different enough to be confident on this point.
 
-A medium-term goal is to support the [WebAssembly](https://webassembly.org)
-target. For now there remains some roadblocks that prevent Colibri from being
-compiled to WASM using the usual methods ([clang](https://clang.llvm.org) or
-[Emscripten](https://emscripten.org/))
+A medium-term goal is to support the [WebAssembly] target. For now there remains
+some roadblocks that prevent Colibri from being compiled to WASM using the usual
+methods ([clang] or [Emscripten])
 
 ## Build & install
 
-The build process depends on [CMake](https://cmake.org). You also have to install
-a toolchain for your platform if needed.
+The build process depends on [CMake]. You also have to install a toolchain for
+your platform if needed.
 
 ### Windows
 
 The easiest and recommended way to build Colibri on Windows is to install the
 Microsoft Visual Studio build tools. You can either download and install them
-manually, or use the package manager [Chocolatey](https://chocolatey.org):
+manually, or use the package manager [Chocolatey]:
 
 ```bat
 choco install visualstudio2017buildtools
@@ -311,10 +310,9 @@ This should build the binaries in the `build` directory.
 
 ## Tests
 
-Colibri requires [PicoTest](https://github.com/fredericbonnet/picotest) for
-testing. The test suite is enabled when CMake detects the PicoTest package. The
-simplest way to do so is to give CMake the path to PicoTest when generating the
-build system, like so:
+Colibri requires [PicoTest] for testing. The test suite is enabled when CMake
+detects the PicoTest package. The simplest way to do so is to give CMake the
+path to PicoTest when generating the build system, like so:
 
 ```sh
 cmake -S . -B build -DCMAKE_MODULE_PATH=</path/to/picotest>
@@ -324,19 +322,48 @@ To run the test suite, simply run `ctest` from within the `build` directory.
 
 ## Documentation
 
-Colibri uses Doxygen for documentation:
+The complete documentation is available here:
 
-http://www.doxygen.nl
+https://fredericbonnet.github.io/colibri
 
-Doxygen can generate HTML documentation files from C sources with specially
-formatted comment blocks. Run `doxgen Doxyfile_public` and
-`doxgen Doxyfile_internal` to generate public and internal docs, in
-`doc/public/html` and `doc/internal/html` respectively.
+The documentation site was built using these great tools:
 
-Documentation generation requires [GraphViz](https://www.graphviz.org) for
-graphs and diagrams. Follow the instructions for your respective platform. On
-Windows you can also install it using Chocolatey:
+- [Doxygen] extracts the documentation from the source code as both HTML and XML
+  formats
+- [seaborg] converts the XML files to Markdown (full disclosure: I'm the author
+  of this tool!)
+- [docsify] generates the documentation site from the Markdown files
 
-```bat
-choco install graphviz
+To rebuild the documentation you'll need the following tools:
+
+- [Doxygen] to process the provided `Doxyfile` and parse the source code
+- [Node.js] to run the build scripts:
+
+```sh
+npm run docs
 ```
+
+If you want to serve the documentation locally you can use the provided script:
+
+```sh
+npm run docsify
+```
+
+[docs]: https://fredericbonnet.github.io/colibri
+[htmldocs]: https://fredericbonnet.github.io/colibri/public/html/index.html
+[doxygen]: http://www.stack.nl/~dimitri/doxygen/
+[seaborg]: https://github.com/fredericbonnet/seaborg
+[docsify]: https://docsify.js.org/
+[node.js]: https://nodejs.org/
+[picotest]: https://github.com/fredericbonnet/picotest
+[chocolatey]: https://chocolatey.org
+[cmake]: https://cmake.org
+[webassembly]: https://webassembly.org
+[clang]: https://clang.llvm.org
+[emscripten]: https://emscripten.org/
+[tcl]: https://www.tcl-lang.org
+[boehm-gc]: https://en.wikipedia.org/wiki/Boehm_garbage_collector
+[ropes]: https://en.wikipedia.org/wiki/Rope_(data_structure)
+[duck-typing]: https://en.wikipedia.org/wiki/Duck_typing
+[mellisuga_helenae_link]: https://commons.wikimedia.org/wiki/File:Bee_hummingbird_(Mellisuga_helenae)_adult_male_in_flight.jpg ":target=_blank"
+[mellisuga_helenae]: https://upload.wikimedia.org/wikipedia/commons/thumb/c/ca/Bee_hummingbird_%28Mellisuga_helenae%29_adult_male_in_flight.jpg/1024px-Bee_hummingbird_%28Mellisuga_helenae%29_adult_male_in_flight.jpg "Bee hummingbird (Melisuga helenae) adult male, Cuba"