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 From eaed9ce88efda1c538e840318419f6a95288e3a0 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Tue, 1 Aug 2017 19:33:48 +0200 Subject: fix: use pinned dependency revisions when generating release archives Signed-off-by: VirtualTam --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index c5dee80e..f2db7d96 100644 --- a/Makefile +++ b/Makefile @@ -155,7 +155,7 @@ release_archive: release_tar release_zip ### download 3rd-party PHP libraries composer_dependencies: clean - composer update --no-dev + composer install --no-dev --prefer-dist find vendor/ -name ".git" -type d -exec rm -rf {} + ### generate a release tarball and include 3rd-party dependencies -- cgit v1.2.3 From 29712e905b8a9bdf1eaa21cbda3ca7c9eb215937 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Tue, 1 Aug 2017 19:25:45 +0200 Subject: documentation: include generated HTML in release archives Closes https://github.com/shaarli/Shaarli/issues/908 Relates to https://github.com/shaarli/Shaarli/pull/772 Signed-off-by: VirtualTam --- Makefile | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index f2db7d96..6483fca7 100644 --- a/Makefile +++ b/Makefile @@ -159,15 +159,18 @@ composer_dependencies: clean find vendor/ -name ".git" -type d -exec rm -rf {} + ### generate a release tarball and include 3rd-party dependencies -release_tar: composer_dependencies +release_tar: composer_dependencies doc_html git archive --prefix=$(ARCHIVE_PREFIX) -o $(ARCHIVE_VERSION).tar HEAD tar rvf $(ARCHIVE_VERSION).tar --transform "s|^vendor|$(ARCHIVE_PREFIX)vendor|" vendor/ + tar rvf $(ARCHIVE_VERSION).tar --transform "s|^doc/html|$(ARCHIVE_PREFIX)doc/html|" doc/html/ gzip $(ARCHIVE_VERSION).tar ### generate a release zip and include 3rd-party dependencies -release_zip: composer_dependencies +release_zip: composer_dependencies doc_html git archive --prefix=$(ARCHIVE_PREFIX) -o $(ARCHIVE_VERSION).zip -9 HEAD - mkdir $(ARCHIVE_PREFIX) + mkdir -p $(ARCHIVE_PREFIX)/{doc,vendor} + rsync -a doc/html/ $(ARCHIVE_PREFIX)doc/html/ + zip -r $(ARCHIVE_VERSION).zip $(ARCHIVE_PREFIX)doc/ rsync -a vendor/ $(ARCHIVE_PREFIX)vendor/ zip -r $(ARCHIVE_VERSION).zip $(ARCHIVE_PREFIX)vendor/ rm -rf $(ARCHIVE_PREFIX) @@ -206,4 +209,3 @@ htmlpages: rm -r venv doc_html: authors htmlpages - -- cgit v1.2.3