First version

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a82d6b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+Poseidoc
+========
+
+A documentation system built on Doxygen and Pandoc
+
+Overview
+--------
+
+## For now
+
+- Takes Doxygen-generated XML input
+- Outputs Pandoc's JSON AST
+
+## In the future
+
+- Will generate the Doxyfile and the XML files for you
+- Will generate the output directly
+        - HTML is a priority
+        - Then PDF / LaTeX
+        - If the project is well designed, other outputs should be supported out of
+          the box thanks to Pandoc
+- Per-project TOML configuration
+
+Quick Start
+-----------
+
+- Have a documented project
+- Generate a Doxyfile that outputs XML and **without** Markdown support (for
+  example with `doxywizard`)
+- `cargo run -- <xml file> | pandoc --from json --to html --standalone
+  --self-contained --toc --css <your css here> --output <output file>.html`
+
+Goals
+-----
+
+- It needs to be simple and very easy to setup
+- It needs to be configurable by project
+- It should encourage people to write documentation
+- It should encourage people to read documentation
+
+- Warnings? Maybe?
+
+### Interface design goals
+
+- It should be beautiful
+- It should be easy to get wanted information from a glance
+- It should be accessible
+
+### Technical goals
+
+- Little to no JavaScript
+- The generated markup must be simple and semantic
+- Sensible defaults for Doxygen and Pandoc
+- But both Doxygen and Pandoc must be completely configurable