Make a clear distinction:
* The README.rst is about the project and how to install and develop
Hawkmoth. It's mainly for the GitHub landing page.
* The Sphinx documentation under doc is about Hawkmoth configuration and
usage.
Make references between the two, but don't try to mix them up. This will
help in further cleanups of the documentation, at the relatively small
cost of duplicating some of the introductory text.
Add a rst2html Makefile rule to be able to check the README.rst is all
right, since it's not included in the Sphinx build. Use 'make
README.html'.
---
Makefile.rules | 3 +++
doc/README.rst | 1 -
doc/index.rst | 27 ++++++++++++++++++++++++---
3 files changed, 27 insertions(+), 4 deletions(-)
delete mode 120000 doc/README.rst
diff --git a/Makefile.rules b/Makefile.rules
index cc03cc9b1b75..d2d37e6eab99 100644
--- a/Makefile.rules
+++ b/Makefile.rules
@@ -15,6 +15,9 @@ endif
# Otherwise, print the full command line.
quiet ?= $($1)
+%.html: %.rst
+ rst2html --strict --no-raw $< > $@
+
.PHONY: clean
clean:
$(call quiet,RM,CLEAN) -rf $(CLEAN)
diff --git a/doc/README.rst b/doc/README.rst
deleted file mode 120000
index 89a0106941ff..000000000000
--- a/doc/README.rst
+++ /dev/null
@@ -1 +0,0 @@
-../README.rst
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index 6727f470d999..2981a40b0b6b 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,12 +1,33 @@
-Hawkmoth Documentation
-======================
+Hawkmoth - Sphinx Autodoc for C
+===============================
+
+Hawkmoth is a minimalistic Sphinx_ :any:`C Domain <sphinx:c-domain>` autodoc
+directive extension to incorporate formatted C source code comments written in
+reStructuredText_ into Sphinx based documentation. It uses Clang Python
Bindings
+for parsing, and generates C Domain directives for C API documentation, and
+more. In short, Hawkmoth is Sphinx Autodoc for C.
+
+Hawkmoth aims to be a compelling alternative for documenting C projects using
+Sphinx, mainly through its simplicity of design, implementation and use.
+
+Please see the `Hawkmoth project GitHub page`_ (or README.rst in the source
+repository) for information on how to obtain, install, and contribute to
+Hawkmoth, as well as how to contact the developers.
+
+Read on for information about Hawkmoth usage; how to configure and use the
+extension and how to write documentation comments, with examples.
+
+.. _Sphinx: http://www.sphinx-doc.org
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+.. _Hawkmoth project GitHub page: https://github.com/jnikula/hawkmoth
Contents:
.. toctree::
:maxdepth: 2
- README
extension
syntax
examples
--
2.20.1
