From 53ed6d7d1e678d7486337ce67a2f17b30bac21ac Mon Sep 17 00:00:00 2001 From: nodiscc 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 () part -htmlsidebar: - @echo '
' > 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 '
' >> 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 From f47aa40c12ec63a60d2edc959314a0a05f6fe610 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Tue, 4 Jul 2017 21:26:27 +0200 Subject: makefile: remove obsolete 'doc' target official documentation can now be found in doc/md/ --- Makefile | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index 1ddd60f8..2064303a 100644 --- a/Makefile +++ b/Makefile @@ -192,13 +192,6 @@ doxygen: clean @rm -rf doxygen @( cat Doxyfile ; echo "PROJECT_NUMBER=`git describe`" ) | doxygen - -### update the local copy of the documentation -doc: clean - @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: @@ -218,4 +211,5 @@ htmlpages: find doc/html/ -type f -exec chmod a-x '{}' \; rm -r venv -doc_html: authors doc htmlpages +doc_html: authors htmlpages + -- cgit v1.2.3 From 8bf94136e10c64496711c8f66a4f58f89c515360 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Tue, 4 Jul 2017 21:30:50 +0200 Subject: makefile: remove [[link]] -> [link](url) conversion logic all links in documentation have been converted to standard markdown link syntax --- Makefile | 6 ------ 1 file changed, 6 deletions(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index 2064303a..c5dee80e 100644 --- a/Makefile +++ b/Makefile @@ -198,12 +198,6 @@ doxygen: clean # - convert GitHub-flavoured relative links to standard Markdown # - generate html documentation with mkdocs 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; \ -- cgit v1.2.3