consolidate docs into a mdbook book

.reuse/dep5

@@ -11,3 +11,7 @@ License: Apache-2.0
 Files: tests/fmt/cases/*
 Copyright: Stone Tickle <[email protected]>
 License: GPL-3.0-only
+
+Files: doc/book/*
+Copyright: Stone Tickle <[email protected]>
+License: GPL-3.0-only

README.md

@@ -24,7 +24,8 @@ dependencies.
 
 `muon` is close to feature-complete with the core of meson for `c` and `c++`.
 
-See the status page for each version for more detailed information.
+See the [Muon Reference](https://docs.muon.build/ref) for more detailed
+information.
 
 Things missing include:
 
@@ -33,7 +34,7 @@ Things missing include:
 - dependencies with a custom configuration tool
 - some modules
 
-Other differences from meson are described in `doc/differences.md`
+Other differences from meson are described in the [Muon Docs].
 
 If you want to contribute, try using `muon` to build your favorite project.
 Patches and bug reports welcome!
@@ -136,3 +137,4 @@ originally based on `boson`, though has since been almost completely rewritten.
 [ninja implementation]: https://git.sr.ht/~lattis/muon/tree/master/item/src/external/samurai/README.md
 [ci dashboard]: https://muon.build/muon_ci.html
 [Features]: https://git.sr.ht/~lattis/muon/tree/master/item/doc/features.md
+[Muon Docs]: https://docs.muon.build/differences.html

doc/book/.gitignore

@@ -0,0 +1 @@
+book

doc/book/book.toml

@@ -0,0 +1,10 @@
+[book]
+authors = ["Stone Tickle"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Muon Docs"
+
+[output.html]
+default-theme = "muon"
+preferred-dark-theme = "muon"

doc/book/meson.build

@@ -0,0 +1,49 @@
+mdbook = find_program('mdbook')
+
+custom_target(
+    output: 'reference.html',
+    command: [muon, 'internal', 'dump_docs'],
+    capture: true,
+    build_by_default: true,
+)
+
+custom_target(
+    output: 'book',
+    input: files(
+        'src/SUMMARY.md',
+        'src/chapter_1.md',
+        'src/contributing.md',
+        'src/differences.md',
+        'src/features.md',
+        'src/internals.md',
+        'src/intro.md',
+        'src/release_notes.md',
+        'src/scripting.md',
+        'src/scripting/adding_new_builtin.md',
+        'src/scripting/additional_functions.md',
+        'src/scripting/function_behavior_changes.md',
+        'src/scripting/function_declaration.md',
+        'src/scripting/module_structure.md',
+        'src/scripting/mutability.md',
+        'src/scripting/rationale.md',
+        'src/scripting/scope.md',
+        'src/scripting/type_specifiers.md',
+        'theme/book.js',
+        'theme/css/variables.css',
+        'book.toml',
+    ),
+    command: [
+        mdbook,
+        'build',
+        meson.current_source_dir(),
+        '-d', meson.current_build_dir(),
+    ],
+    build_by_default: true,
+)
+
+foreach ext : ['svg', 'png']
+    fs.copyfile(
+        '../website/muon_logo.svg',
+        'favicon.@0@'.format(ext)
+    )
+endforeach

doc/book/src/SUMMARY.md

@@ -0,0 +1,18 @@
+# Summary
+
+# Muon Docs
+- [Introduction](intro.md)
+- [Features](features.md)
+- [Functional Differences](differences.md)
+- [Contributing](contributing.md)
+- [Scripting](scripting.md)
+    - [Mutability](scripting/mutability.md)
+    - [Function declaration](scripting/function_declaration.md)
+    - [Scope](scripting/scope.md)
+    - [Type Specifiers](scripting/type_specifiers.md)
+    - [Function Behavior Changes](scripting/function_behavior_changes.md)
+    - [Module Structure](scripting/module_structure.md)
+    - [Adding a New Builtin Script Module](scripting/adding_new_builtin.md)
+    - [Rationale](scripting/rationale.md)
+- [Muon Internals](internals.md)
+- [Release Notes](release_notes.md)

doc/book/src/contributing.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for considering contributing to muon.  Please send patches and questions
+to <~lattis/[email protected]>.  Alternatively you may make a pull request at
+<https://github.com/muon-build/muon>. Before making any big changes, please send
+a proposal to the mailing list or open an issue so I can give you some pointers,
+and make sure you don't waste your time.
+
+## Contribution areas
+
+There are two main ways to contribute to Muon:
+- Add a [script module](scripting/adding_new_builtin.md).  There are several
+  unimplemented modules that could likely be easily written as a script module.
+  See `src/script/modules` for examples.
+- Work on the runtime.  Please read the documentation on [Muon
+  Internals](internals.md).
+
+## C Style
+
+Muon uses a style similar to the linux kernel.  A few differences are:
+
+- the return type of a function goes on the line above its declaration.
+  e.g.
+
+  ```c
+  int
+  main(void)
+  {
+          return 0;
+  }
+  ```
+
+- it still goes on the same line in a function prototype
+  e.g.
+
+  ```c
+  int main(void);
+  ```
+
+- never omit braces for single statement if, else, for, while,  etc.
+- avoid function-like macros except in exceptional cases
+- it is OK (but not great) if your line is more than 80 characters
+- please use fixed-width integer types (e.g. `uint32_t`, `uint64_t`, `uint8_t`)
+  whenever possible
+
+As usual, just try to follow the style of surrounding code.

doc/differences.md → doc/book/src/differences.md

@@ -1,9 +1,4 @@
-<!--
-SPDX-FileCopyrightText: Stone Tickle <[email protected]>
-SPDX-License-Identifier: GPL-3.0-only
--->
-
-# Differences between muon and Meson
+# Differences Between Muon and Meson
 
 This document describes functional differences between muon and Meson.  None of
 these is a set-in-stone design decision, just a reflection of the current state

doc/book/src/features.md

@@ -0,0 +1,49 @@
+# Features
+
+In addition to trying maintain Meson compatibility, Muon also has a few features
+of its own.
+
+### muon analyze
+
+muon has a full-featured static analyzer for meson build scripts.  It can check
+for undefined variables, unused variables, variable reassignment to different
+types, undefined functions, undefined kwargs, missing required args, methods,
+operator typechecking, and more.
+
+See `muon analyze -h` for more information.
+
+### muon fmt
+
+A formatter for meson build scripts.
+
+See `muon fmt -h` for more information.
+
+### Debugger (WIP)
+
+Muon has an interactive gdb-like debugger.  You can trigger it by setting
+breakpoints with the -b flag on either setup or internal eval subcommands.
+Inside the debugger you can look around, evaluate expressions, and step through
+code.
+
+### Built-In Ninja (samurai)
+
+Muon has an embedded copy of [samurai](https://github.com/michaelforney/samurai)
+(at `src/external/samurai`) which has been ported to use muon's cross-platform
+layer and so works on all the platforms muon supports.  This means you can just
+grab a single muon binary and that's all you need to build your project.
+
+### VM
+
+Muon's language runtime is a fully featured stack-based VM.  All scripts are
+compiled to bytecode before execution.  This runtime is powerful enough to host
+modules as well as basic cross-platform scripting.  See
+[Scripting](scripting.md) for more information
+
+### Fast
+
+Muon is orders of magnitude faster than meson when your scripts are interpreter-
+bound. This means that as long as muon doesn't have to shell out to the compiler
+it is very fast.
+
+Typically the most speedup can be seen during re-configs where most compiler
+checks have been cached.

doc/contributing.md → doc/book/src/internals.md

@@ -1,47 +1,4 @@
-<!--
-SPDX-FileCopyrightText: Stone Tickle <[email protected]>
-SPDX-FileCopyrightText: Andrea Pappacoda <[email protected]>
-SPDX-License-Identifier: GPL-3.0-only
--->
-
-# Contributions
-
-Hello, thanks for considering contributing to muon.  Please send patches and
-questions to <~lattis/[email protected]>.
-Before making any big changes, please send a proposal to the mailing list so I
-can give you some pointers, and make sure you don't waste your time.
-
-# Style
-
-Muon uses a style similar to the linux kernel.  A few differences are:
-
-- the return type of a function goes on the line above its declaration.
-  e.g.
-
-  ```c
-  int
-  main(void)
-  {
-          return 0;
-  }
-  ```
-
-- it still goes on the same line in a function prototype
-  e.g.
-
-  ```c
-  int main(void);
-  ```
-
-- never omit braces for single statement if, else, for, while,  etc.
-- avoid function-like macros except in exceptional cases
-- it is OK (but not great) if your line is more than 80 characters
-- please use fixed-width integer types (e.g. `uint32_t`, `uint64_t`, `uint8_t`)
-  whenever possible
-
-In general, just try to follow the style of surrounding code.
-
-# Internals
+# Muon Internals
 
 ## Error handling
 

doc/book/src/intro.md

@@ -0,0 +1,9 @@
+# Introduction
+
+This is the official documentation for [Muon](https://muon.build), a
+meson-compatible build system.  Most of the topics discussed are muon-specific.
+
+- For general Meson documentation refer to the [Meson User
+  Manual](https://mesonbuild.com/Manual.html).
+- For documentation on functions and objects refer to the
+  [Muon Reference](https://docs.muon.build).

doc/release_notes.md → doc/book/src/release_notes.md

@@ -1,9 +1,4 @@
-<!--
-SPDX-FileCopyrightText: Stone Tickle <[email protected]>
-SPDX-License-Identifier: GPL-3.0-only
--->
-
-# Release notes
+# Release Notes
 
 ## 0.3.0
 

doc/book/src/scripting.md

@@ -0,0 +1,33 @@
+# Scripting
+
+Muon supports modules and small scripts written in meson.  In order to
+facilitate this, various language features are enabled during module and script
+evaluation.
+
+## Evaluation Modes
+
+Muon's implementation of the meson language includes three evaluation modes:
+
+- `external`: Regular meson.build files external to muon's implementation are
+  evaluated in this mode.
+- `internal`: Any meson file evaluated using `muon internal eval ...` is
+  evaluated in the internal mode.
+- `extended`: A layering of internal on top of external, allows features from both
+  modes to be used simultaneously.  This is the mode that script modules execute
+  in.
+
+Both `internal` and `extended` mode enable the same additional language features
+collectively referred to as *scripting mode*. The primary difference between the
+two modes lies in which functions may be called.  In particular, most functions
+that require a project() or manipulate the build state in any way are not
+available in `internal` mode.
+
+## Scripting Mode
+
+Muon's scripting mode consists of several langauge features as well as
+additional functions and modules.
+
+This guide focuses on the language features.  The additional functions and
+modules are documented in the [Muon Reference](https://docs.muon.build).  All
+functions, modules, and arguments are tagged with their availability in muon's
+different evaluation modes.

doc/book/src/scripting/adding_new_builtin.md

@@ -0,0 +1,9 @@
+# Adding a new builtin script module
+
+After you have written your script module you must register it so it can be
+imported.
+
+All script modules live at `src/script/modules/<module_name>.meson`.  After
+adding the module, you must modify `src/script/meson.build` to register it. muon
+will embed the module source text in the built executable, and when the module
+is import()ed that source will be interpreted.

doc/book/src/scripting/additional_functions.md

@@ -0,0 +1 @@
+# Additional built-in functions

doc/book/src/scripting/function_behavior_changes.md

@@ -0,0 +1,10 @@
+# Function behavior changes
+
+This document lists all modifications to function behavior when a function is
+called during scripting mode vs external mode.
+
+- In regular meson functions which create targets, the `output` parameter is not
+  allowed to contain file separators. This has the effect that targets must only
+  produce outputs which live in the current build directory. In extended meson
+  file separators are permitted in these cases and so extended meson functions
+  can create targets whose outputs may exist in other build directories.

doc/book/src/scripting/function_declaration.md

@@ -0,0 +1,39 @@
+# Function declaration
+
+Function definition is started with the `func` keyword optionally followed by an
+identifier, and a list of arguments enclosed in parenthesis.  If the function
+returns a value it must specify the type of that value by adding `-> <type>`
+after the argument list.
+
+- The identifier is _required_ if the function definition is a statement.
+- The identifier is _not allowed_ if the function definition is in an expression.
+
+Positional and keyword arguments are supported in the argument list.  Positional
+arguments must come first.  Keyword arguments are specified by adding a colon
+(:) to the end of the argument followed by an optional default value. All
+arguments must specify their type by following the argument name with a type
+specifier.
+
+Function definition is ended with the `endfunc` keyword.
+
+Examples:
+
+```meson
+func a() -> int
+    return 1
+endfunc
+
+func b(arg1 int) -> int
+    return arg1
+endfunc
+
+func c(arg1 int, kw str:, kw_with_default str: 'default')
+    message(arg1)
+    message(kw)
+    message(kw_with_default)
+endfunc
+
+d = func()
+    message('hello from an anonymous function!')
+endfunc
+```