Rewrite documentation with Material for mkdocs

- remove doc build from autotools
- don't depend anymore on asciidoc
- don't provide man pages anymore
- new illustrations
- provide mkdocs instructions

Author: stephane

.gitignore

@@ -10,11 +10,10 @@
 .libs
 .DS_Store
 
-# Emacs
-GPATH
-GRTAGS
-GSYMS
-GTAGS
+# Editors
+/*.sublime-*
+/.vscode
+/.venv
 
 # Generated by Autotools
 INSTALL
@@ -28,17 +27,17 @@ Makefile.in
 /configure.scan
 /depcomp
 /install-sh
+/libmodbus.pc
 /libtool
 /ltmain.sh
 /missing
-/libmodbus.pc
 /stamp-h1
 src/modbus-version.h
 src/win32/modbus.dll.manifest
 tests/unit-test.h
 
-/*.sublime-*
-/.vscode
+# mkdocs
+/site
 
 # Binary
 tests/bandwidth-client
@@ -50,8 +49,3 @@ tests/unit-test-client
 tests/unit-test-server
 tests/version
 tests/stamp-h2
-
-# Documentation
-doc/*.html
-doc/*.3
-doc/*.7

CONTRIBUTING.md

@@ -4,7 +4,7 @@ How Do I Submit A Good Bug Report?
 Please, don't send direct emails to Stéphane Raimbault unless you want
 commercial support.
 
-Take care to read the documentation at http://libmodbus.org/documentation/.
+Take care to read the documentation at http://libmodbus.org/.
 
 - *Be sure it's a bug before creating an issue*, in doubt, post a message on
   https://groups.google.com/forum/#!forum/libmodbus or send an email to
@@ -24,6 +24,6 @@ the clients are connected (TCP, RTU, ASCII) and the source code you are using.
 
 - *Enable the debug mode*, libmodbus provides a function to display the content
 of the Modbus messages and it's very convenient to analyze issues
-(http://libmodbus.org/docs/latest/modbus_set_debug.html).
+(http://libmodbus.org/docs/modbus_set_debug/).
 
 Good bug reports provide right and quick fixes!

ISSUE_TEMPLATE.md

@@ -34,7 +34,7 @@ When you get here and you are still convinced that you want to report a bug:
 
 - *Enable the debug mode*, libmodbus provides a function to display the content
    of the Modbus messages and it's very convenient to analyze issues
-   (<http://libmodbus.org/docs/latest/modbus_set_debug.html>).
+   (<http://libmodbus.org/docs/modbus_set_debug/>).
 
 Good bug reports provide right and quick fixes!
 

Makefile.am

@@ -9,7 +9,7 @@ CLEANFILES += libmodbus.pc
 
 dist_doc_DATA = MIGRATION README.md AUTHORS NEWS
 
-SUBDIRS = src doc
+SUBDIRS = src
 
 if BUILD_TESTS
 SUBDIRS += tests

README.md

@@ -1,10 +1,8 @@
-A groovy modbus library
-=======================
+# A groovy modbus library
 
 ![Build Status](https://github.com/stephane/libmodbus/actions/workflows/build.yml/badge.svg)
 
-Overview
---------
+## Overview
 
 libmodbus is a free software library to send/receive data with a device which
 respects the Modbus protocol. This library can use a serial port or an Ethernet
@@ -15,21 +13,15 @@ Protocol Reference Guide which can be obtained from [www.modbus.org](http://www.
 
 The license of libmodbus is *LGPL v2.1 or later*.
 
-The documentation is available as manual pages (`man libmodbus` to read general
-description and list of available functions) or Web pages
-[www.libmodbus.org/documentation/](http://libmodbus.org/documentation/). The
-documentation is licensed under the Creative Commons Attribution-ShareAlike
-License 3.0 (Unported) (<http://creativecommons.org/licenses/by-sa/3.0/>).
-
-The official website is [www.libmodbus.org](http://www.libmodbus.org).
+The official website is [www.libmodbus.org](http://www.libmodbus.org). The
+website contains the latest version of the documentation.
 
 The library is written in C and designed to run on Linux, Mac OS X, FreeBSD, Embox,
 QNX and Windows.
 
 You can use the library on MCUs with Embox RTOS.
 
-Installation
-------------
+## Installation
 
 You will only need to install automake, autoconf, libtool and a C compiler (gcc
 or clang) to compile the library and asciidoc and xmlto to generate the
@@ -59,19 +51,7 @@ automake libtool`.
 
 To build under Embox, you have to use its build system.
 
-Documentation
--------------
-
-The documentation is available [online](http://libmodbus.org/documentation) or
-as manual pages after installation.
-
-The documentation is based on
-[AsciiDoc](http://www.methods.co.nz/asciidoc/).  Only man pages are built
-by default with `make` command, you can run `make htmldoc` in *doc* directory
-to generate HTML files.
-
-Testing
--------
+## Testing
 
 Some tests are provided in *tests* directory, you can freely edit the source
 code to fit your needs (it's Free Software :).
@@ -87,7 +67,15 @@ By default, all TCP unit tests will be executed (see --help for options).
 
 It's also possible to run the unit tests with `make check`.
 
-To report a bug or to contribute
---------------------------------
+## To report a bug or to contribute
 
 See [CONTRIBUTING](CONTRIBUTING.md) document.
+
+## Documentation
+
+You can serve the local documentation with:
+
+```shell
+pip install mkdocs-material
+mkdocs serve
+```

acinclude.m4

@@ -94,9 +94,6 @@ AC_CHECK_HEADERS([ \
     unistd.h \
 ])
 
-# Check whether to build docs / install man pages
-AC_LIBMODBUS_CHECK_BUILD_DOC
-
 # Cygwin defines IPTOS_LOWDELAY but can't handle that flag so it's necessary to
 # workaround that problem and Cygwin doesn't define MSG_DONTWAIT.
 AC_CHECK_DECLS([__CYGWIN__])
@@ -161,7 +158,6 @@ AC_CONFIG_FILES([
         src/modbus-version.h
         src/win32/modbus.dll.manifest
         tests/Makefile
-        doc/Makefile
         libmodbus.pc
 ])
 
@@ -179,6 +175,5 @@ AC_MSG_RESULT([
         cflags:                 ${CFLAGS}
         ldflags:                ${LDFLAGS}
 
-        documentation:          ${ac_libmodbus_build_doc}
         tests:                  ${enable_tests}
 ])