From 53ed6d7d1e678d7486337ce67a2f17b30bac21ac Mon Sep 17 00:00:00 2001
From: nodiscc <nodiscc@gmail.com>
Date: Thu, 26 Jan 2017 18:52:54 +0100
Subject: Generate HTML documentation using MkDocs (WIP)

MkDocs is a static site generator geared towards building project documentation.
Documentation source files are written in Markdown, and configured with a single YAML file.

 * http://www.mkdocs.org/
 * http://www.mkdocs.org/user-guide/configuration/

Ref. #312

* remove pandoc-generated HTML documentation
* move markdown doc to doc/md/,
* mkdocs.yml:
  * generate HTML doc in doc/html
  * add pages TOC/ordering
  * use index.md as index page
* Makefile: remove execute permissions from generated files
* Makefile: rewrite htmlpages GFM to markdown conversion using sed:
   awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks
* Add mkdocs.yml to .gitattributes, exclude this file from release archives
* Makefile: rename: htmldoc -> doc_html target
* run make doc: pull latest markdown documentation from wiki
* run make htmlpages: update html documentation
---
 Makefile | 52 +++++++++++++++++++---------------------------------
 1 file changed, 19 insertions(+), 33 deletions(-)

(limited to 'Makefile')

diff --git a/Makefile b/Makefile
index 1d8a73a2..1ddd60f8 100644
--- a/Makefile
+++ b/Makefile
@@ -194,42 +194,28 @@ doxygen: clean
 
 ### update the local copy of the documentation
 doc: clean
-	@rm -rf doc
-	@git clone https://github.com/shaarli/Shaarli.wiki.git doc
-	@rm -rf doc/.git
-
-### Generate a custom sidebar
-#
-# Sidebar content:
-#  - convert GitHub-flavoured relative links to standard Markdown
-#  - trim HTML, only keep the list (<ul>[...]</ul>) part
-htmlsidebar:
-	@echo '<div id="local-sidebar">' > doc/sidebar.html
-	@awk 'BEGIN { FS = "[\\[\\]]{2}" }'\
-	'm = /\[/ { t=$$2; gsub(/ /, "-", $$2); print $$1"["t"]("$$2".html)"$$3 }'\
-	'!m { print $$0 }' doc/_Sidebar.md > doc/tmp.md
-	@pandoc -f markdown -t html5 -s doc/tmp.md | awk '/(ul>|li>)/' >> doc/sidebar.html
-	@echo '</div>' >> doc/sidebar.html
-	@rm doc/tmp.md
+	@rm -rf doc/md/
+	@git clone https://github.com/shaarli/Shaarli.wiki.git doc/md
+	mv doc/md/Home.md doc/md/index.md
+	@rm -rf doc/md/.git
 
 ### Convert local markdown documentation to HTML
 #
 # For all pages:
-#  - infer title from the file name
 #  - convert GitHub-flavoured relative links to standard Markdown
-#  - insert the sidebar menu
+#  - generate html documentation with mkdocs
 htmlpages:
-	@for file in `find doc/ -maxdepth 1 -name "*.md"`; do \
-		base=`basename $$file .md`; \
-		sed -i "1i #$${base//-/ }" $$file; \
-		awk 'BEGIN { FS = "[\\[\\]]{2}" }'\
-	'm = /\[/ { t=$$2; gsub(/ /, "-", $$2); print $$1"["t"]("$$2".html)"$$3 }'\
-	'!m { print $$0 }' $$file > doc/tmp.md; \
-		mv doc/tmp.md $$file; \
-		pandoc -f markdown_github -t html5 -s \
-			-c "github-markdown.css" \
-			-T Shaarli -M pagetitle:"$${base//-/ }" -B doc/sidebar.html \
-			-o doc/$$base.html $$file; \
-	done;
-
-htmldoc: authors doc htmlsidebar htmlpages
+	# Rename local [[links]] to regular links.
+	@for file in `find doc/md/ -maxdepth 1 -name "*.md"`; do \
+		sed -e "s/\[\[\(.*\)\]\]/[\1](\1)/g" "$$file" > doc/md/tmp.md; \
+		mv doc/md/tmp.md $$file; \
+	done
+
+	python3 -m venv venv/
+	bash -c 'source venv/bin/activate; \
+	pip install mkdocs; \
+	mkdocs build'
+	find doc/html/ -type f -exec chmod a-x '{}' \;
+	rm -r venv
+
+doc_html: authors doc htmlpages
-- 
cgit v1.2.3