From 2cf77ff778eff2292159045bc6f30321cecfd65a Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 20 Oct 2016 16:16:17 -0400 Subject: [PATCH] Add support for ebook generation in ePUB and mobi format --- doc/Makefile | 13 ++++++++----- doc/README | 26 +++++++++++++++++++++++++- doc/src/JPG/lammps-logo.png | Bin 0 -> 4900 bytes doc/utils/sphinx-config/conf.py | 23 +++++++++++++++++++++++ 4 files changed, 56 insertions(+), 6 deletions(-) create mode 100644 doc/src/JPG/lammps-logo.png diff --git a/doc/Makefile b/doc/Makefile index ba930d71db..e3614e1627 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -22,7 +22,7 @@ endif SOURCES=$(wildcard src/*.txt) OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst) -.PHONY: help clean-all clean epub html pdf old venv +.PHONY: help clean-all clean ebook html pdf old venv # ------------------------------------------ @@ -32,7 +32,7 @@ help: @echo " pdf create Manual.pdf and Developer.pdf in this dir" @echo " old create old-style HTML doc pages in old dir" @echo " fetch fetch HTML and PDF files from LAMMPS web site" - @echo " epub create ePUB file with manual in this dir" + @echo " ebook create ePUB/mobi file with manual in this dir" @echo " clean remove all intermediate RST files" @echo " clean-all reset the entire build environment" @echo " txt2html build txt2html tool" @@ -64,16 +64,19 @@ html: $(OBJECTS) @rm -rf html/USER/*/*.[sg]* @echo "Build finished. The HTML pages are in doc/html." -epub: $(OBJECTS) +ebook: $(OBJECTS) + @mkdir -p epub + @cp src/JPG/lammps-logo.png epub/ @(\ . $(VENV)/bin/activate ;\ cp -r src/* $(RSTDIR)/ ;\ sphinx-build -j 8 -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\ deactivate ;\ ) - @mv -f epub/LAMMPS.epub . + @-(cd epub; ebook-convert LAMMPS.epub LAMMPS.mobi ) + @-mv -f epub/LAMMPS.epub epub/LAMMPS.mobi . @rm -rf epub - @echo "Build finished. The ePUB file LAMMPS.epub is created/updated." + @echo "Build finished. The ebook file(s) is/are created." pdf: utils/txt2html/txt2html.exe @(\ diff --git a/doc/README b/doc/README index ea0edc0356..12ae7f3f40 100644 --- a/doc/README +++ b/doc/README @@ -1,13 +1,15 @@ LAMMPS Documentation Depending on how you obtained LAMMPS, this directory has 2 or 3 -sub-directories and optionally 2 PDF files: +sub-directories and optionally 2 PDF files and 2 ebook files: src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) tools tools and settings for building the documentation Manual.pdf large PDF version of entire manual Developer.pdf small PDF with info about how LAMMPS is structured +LAMMPS.epub Manual in ePUB format +LAMMPS.mobi Manual in mobi format (required for for Kindle) If you downloaded LAMMPS as a tarball from the web site, all these directories and files should be included. @@ -49,6 +51,9 @@ make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) make old # generate old-style HTML pages in old dir via txt2html make fetch # fetch HTML doc pages and 2 PDF files from web site # as a tarball and unpack into html dir and 2 PDFs +make ebook # generate e-book LAMMPS.epub in ePUB format using Sphinx + # optionally convert it to mobi format (for Kindle + # readers, requires "ebook-convert" from Calibre) make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data @@ -91,3 +96,22 @@ This will install virtualenv from the Python Package Index. ---------------- Installing prerequisites for PDF build + +[TBA] + +---------------- + +Installing prerequisites for ebook build + +## ePUB + +Same as for HTML. This uses the same tools and configuration +files as the HTML tree. + +## mobi + +For converting the generated ePUB file to a mobi format file +(for e-book readers, that cannot read ePUB), you also need to have +the 'ebook-convert' tool from the "calibre" software installed. +http://calibre-ebook.com/ + diff --git a/doc/src/JPG/lammps-logo.png b/doc/src/JPG/lammps-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..ae5ba2d8ad56ec55dc7a54ee8be0a21d44003b30 GIT binary patch literal 4900 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 B&!PYT literal 0 HcmV?d00001 diff --git a/doc/utils/sphinx-config/conf.py b/doc/utils/sphinx-config/conf.py index d892178346..2b4950519a 100644 --- a/doc/utils/sphinx-config/conf.py +++ b/doc/utils/sphinx-config/conf.py @@ -276,4 +276,27 @@ texinfo_documents = [ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False +# -- Options for ePUB output ---------------------------------------------- + +epub_title = 'LAMMPS Documentation - ' + get_lammps_version() + +epub_cover = ('lammps-logo.png', '') + +epub_description = """ +This is the Manual for the LAMMPS software package. + +LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel +Simulator and is a classical molecular dynamics simulation code +designed to run efficiently on parallel computers. It was developed +at Sandia National Laboratories, a US Department of Energy facility, +with funding from the DOE. It is an open-source code, distributed +freely under the terms of the GNU Public License (GPL). + +The primary author of the code is Steve Plimpton, who can be emailed +at sjplimp@sandia.gov. The LAMMPS WWW Site at lammps.sandia.gov has +more information about the code and its uses. +""" + +epub_author = 'The LAMMPS Developers' +