Initialize doc

doc/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

doc/blog/2024-08-07-hello/index.md

@@ -0,0 +1,8 @@
+---
+slug: hello
+title: Hello
+authors: [mbarbin]
+tags: [hello]
+---
+
+Hello! I've just launched a blog section within the commandlang documentation, powered by Docusaurus. This new space is designed to keep you updated with all things related to commandlang. Stay tuned for more updates and insights. Happy reading!

doc/blog/authors.yml

@@ -0,0 +1,5 @@
+mbarbin:
+  name: Mathieu Barbin
+  title: Author & Maintainer of commandlang
+  url: https://github.com/mbarbin
+  image_url: https://github.com/mbarbin.png

doc/blog/tags.yml

@@ -0,0 +1,4 @@
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description

doc/docs/explanation/README.md

@@ -0,0 +1,32 @@
+# Explanation
+
+Welcome to the Explanation section of the `commandlang` documentation. Here, we delve into the details of how `commandlang` works, its design principles, and our future plans. This section is intended to provide a deeper understanding of the project for developers and contributors.
+
+## Architecture
+
+`commandlang` is composed of several parts:
+
+- **Core Specification Language**: A kernel command-line parsing specification language written as an OCaml EDSL.
+- **OCaml Library**: Exposes a single module, `Commandlang.Command`, with no dependencies, to build command-line parsers in total abstraction using ergonomic helpers.
+- **Translation Libraries**: Convert `commandlang` parsers at runtime into `cmdliner`, `core.command`, or `climate` parsers.
+
+## Experimental Status
+
+`commandlang` is currently under construction and considered experimental. We are actively seeking feedback to validate our design and engage with other declarative command-line enthusiasts.
+
+## Future Plans
+
+In this section, we outline some areas of uncertainty regarding the feasibility of our design in detail. These are the areas we plan to explore next:
+
+1. **Anonymous Arguments (Positional Arguments)**
+2. **Generation of Complex Man Pages**
+3. **Auto-Completion**
+
+For more details, refer to the [Future Plans](./future_plans.md) section.
+
+## Acknowledgements
+
+- We are grateful for the years of accumulated work and experience that have resulted in high-quality CLI libraries like `cmdliner` and `core.command`
+- `climate`'s early programming interface was a great source of inspiration. We are very thankful for their work on auto-completion and excited to see where the `climate` project goes next.
+
+For more details, refer to the Acknowledgements section of the project on GitHub.

doc/docs/explanation/future_plans.md

@@ -0,0 +1,23 @@
+# Future Plans
+
+In this section, we outline some areas of uncertainty regarding the feasibility of our design in detail. These are the areas we plan to explore next.
+
+## Anonymous Arguments (Positional Arguments)
+
+One of the key areas we need to investigate further is the handling of anonymous arguments, also known as positional arguments in `cmdliner` and `climate`. Due to the differences in how these arguments are managed in `core.command`, translating them may not be as straightforward as it is for named arguments.
+
+However, we have a good intuition that by reducing some of the expressiveness of what we allow to construct, we can solve cases that are sufficient in practice. For example, enforcing that positional arguments be defined in left-to-right order in the specification might be a viable approach.
+
+## Generation of Complex Man Pages
+
+Another area of focus is the generation of complex man pages. `cmdliner` has excellent support for these. Currently, we have added basic support for one-line summaries of help messages to get started. However, we believe we could reuse most of the design of `cmdliner` and add it as optional information to the specification language.
+
+The rendering to simple strings could be exported by a standalone `cmdliner` helper library to reduce dependencies. We could then reuse and integrate this in the translation to `core.command` and `climate`. This part is more prospective and may require some coordination with the developers of other libraries.
+
+## Auto-Completion
+
+The third point is by far the most challenging but also a source of significant added value: auto-completion. This has been a highly anticipated feature within the community, and we have recently seen progress in this area, particularly with the `climate` developers working on integrating support for auto-completion.
+
+We envision a potential hybrid translation mode where a `commandlang` command is translated into both `cmdliner` and `climate` — `cmdliner` for runtime execution and `climate` to generate completion scripts. This approach leaves the question of reentrant completion as future work.
+
+Given the ongoing developments in other libraries regarding auto-completion, we will carefully consider how `commandlang`'s unique architecture can accommodate and leverage these changes. This will require thoughtful planning and possibly significant adjustments as the landscape evolves.

doc/docs/guides/README.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This part of the documentation is currently empty.

doc/docs/reference/dune

@@ -0,0 +1,5 @@
+(mdx
+ (deps
+  (package commandlang)
+  (glob_files *.txt))
+ (preludes prelude.txt))

doc/docs/reference/odoc.md

@@ -0,0 +1,3 @@
+# OCaml Packages Documentation
+
+You can view the published odoc pages here: [https://mbarbin.github.io/commandlang/odoc/](https://mbarbin.github.io/commandlang/odoc/).

doc/docs/reference/prelude.txt

@@ -0,0 +1 @@
+#require "commandlang" ;;