diff --git a/docs/Makefile b/docs/Makefile index f7c2e4a..84716be 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -59,7 +59,7 @@ dist: html cp -al build/html . @echo "Build finished. Final docs are in html/" -html: api autoconfig automagic +html: jsapi api autoconfig automagic html_noapi: clean_api autoconfig automagic html html_noapi: @@ -80,6 +80,9 @@ source/config/options/generated: python autogen_config.py @echo "Created docs for config options" +jsapi: + jsdoc -c jsdoc_config.json -d ./build/jsapi_html/ + api: source/api/generated/gen.txt source/api/generated/gen.txt: diff --git a/docs/README.rst b/docs/README.rst index 7d550fa..0cfe596 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -11,20 +11,22 @@ sphinx jsdoc On Debian-based systems, you should be able to run:: - sudo apt-get install sphinx npm + sudo apt-get install python-sphinx npm sudo npm install -g jsdoc@"<=3.3.0" The documentation gets built using ``make``, and comes in several flavors. -``make html`` - build the API and narrative documentation web pages, this -is the the default ``make`` target, so running just ``make`` is equivalent to -``make html``. +``make html`` - build the API (both Javascript and Python) and narrative +documentation web pages, this is the the default ``make`` target, so +running just ``make`` is equivalent to ``make html``. ``make html_noapi`` - same as above, but without running the auto-generated API docs. When you are working on the narrative documentation, the most time consuming portion of the build process is the processing and rending of the API documentation. This build target skips that. +``make jsapi`` - build Javascript auto-generated API documents. + ``make pdf`` will compile a pdf from the documentation. You can run ``make help`` to see information on all possible make targets. diff --git a/docs/conf.json b/docs/jsdoc_config.json similarity index 90% rename from docs/conf.json rename to docs/jsdoc_config.json index 67cc9a2..7299244 100644 --- a/docs/conf.json +++ b/docs/jsdoc_config.json @@ -11,6 +11,5 @@ "templates": { "cleverLinks": false, "monospaceLinks": false - }, - "destination": "./out/" + } } \ No newline at end of file diff --git a/docs/make.cmd b/docs/make.cmd index 00b1b74..5e3503d 100644 --- a/docs/make.cmd +++ b/docs/make.cmd @@ -5,6 +5,7 @@ SETLOCAL SET SPHINXOPTS= SET SPHINXBUILD=sphinx-build +SET JSDOC=jsdoc SET PAPER= SET SRCDIR=source @@ -43,6 +44,10 @@ FOR %%L IN (html pickle htmlhelp latex changes linkcheck) DO ( ) IF "%1" == "clean" ( + %JSDOC% -c jsdoc_config.json -d ./build/jsapi_html/ +) + +IF "%1" == "jsapi" ( RD /s /q build dist %SRCDIR%\api\generated 2>NUL IF ERRORLEVEL 0 ECHO Build environment cleaned! GOTO END @@ -52,6 +57,7 @@ ECHO. ECHO Please use "make [target]" where [target] is one of: ECHO. ECHO html to make standalone HTML files +ECHO jsapi to make standalone HTML files for the Javascript API ECHO pickle to make pickle files (usable by e.g. sphinx-web) ECHO htmlhelp to make HTML files and a HTML help project ECHO latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter