From 35b9921582ff30eb1b7c343cfcf45cc41208a045 Mon Sep 17 00:00:00 2001 From: Vsevolod Solovyov Date: Mon, 24 Nov 2008 16:55:06 +0200 Subject: Fixes #32. sphinx-quickstart adapted for windows --- sphinx/quickstart.py | 130 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 125 insertions(+), 5 deletions(-) (limited to 'sphinx/quickstart.py') diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 03024535..998d93fb 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -318,6 +318,109 @@ linkcheck: \t "or in %(rbuilddir)s/linkcheck/output.txt." ''' +BATCHFILE = '''\ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set ALLSPHINXOPTS=-d %(rbuilddir)s/doctrees %%SPHINXOPTS%% %(rsrcdir)s +if NOT "%%PAPER%%" == "" ( +\tset ALLSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%ALLSPHINXOPTS%% +) + +if "%%1" == "" goto help + +if "%%1" == "help" ( +\t:help +\techo.Please use `make-docs ^` where ^ is one of +\techo. html to make standalone HTML files +\techo. pickle to make pickle files +\techo. json to make JSON files +\techo. htmlhelp to make HTML files and a HTML help project +\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter +\techo. changes to make an overview over all changed/added/deprecated items +\techo. linkcheck to check all external links for integrity +\tgoto end +) + +if "%%1" == "clean" ( +\tfor /d %%%%i in (%(rbuilddir)s\*) do rmdir /q /s %%%%i +\tdel /q /s %(rbuilddir)s\* +\tgoto end +) + +if "%%1" == "html" ( +\tcall :mkdir %(rbuilddir)s\html %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b html %%ALLSPHINXOPTS%% %(rbuilddir)s/html +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/html. +\tgoto end +) + +if "%%1" == "web" goto pickle + +if "%%1" == "pickle" ( +\t:pickle +\tcall :mkdir %(rbuilddir)s\pickle %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle +\techo. +\techo.Build finished; now you can process the pickle files. +\tgoto end +) + +if "%%1" == "json" ( +\tcall :mkdir %(rbuilddir)s\json %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b json %%ALLSPHINXOPTS%% %(rbuilddir)s/json +\techo. +\techo.Build finished; now you can process the JSON files. +\tgoto end +) + +if "%%1" == "htmlhelp" ( +\tcall :mkdir %(rbuilddir)s\htmlhelp %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b htmlhelp %%ALLSPHINXOPTS%% %(rbuilddir)s/htmlhelp +\techo. +\techo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %(rbuilddir)s/htmlhelp. +\tgoto end +) + +if "%%1" == "latex" ( +\tcall :mkdir %(rbuilddir)s\latex %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %(rbuilddir)s/latex +\techo. +\techo.Build finished; the LaTeX files are in %(rbuilddir)s/latex. +\tgoto end +) + +if "%%1" == "changes" ( +\tcall :mkdir %(rbuilddir)s\changes %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b changes %%ALLSPHINXOPTS%% %(rbuilddir)s/changes +\techo. +\techo.The overview file is in %(rbuilddir)s/changes. +\tgoto end +) + +if "%%1" == "linkcheck" ( +\tcall :mkdir %(rbuilddir)s\linkcheck %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b linkcheck %%ALLSPHINXOPTS%% %(rbuilddir)s/linkcheck +\techo. +\techo.Link check complete; look for any errors in the above output ^ +or in %(rbuilddir)s/linkcheck/output.txt. +\tgoto end +) + +goto end + +:mkdir %%1 %%2 +\tIF NOT EXIST %%1 mkdir %%1 +\tIF NOT EXIST %%2 mkdir %%2 +\texit /b + +:end +''' + def mkdir_p(dir): if path.isdir(dir): @@ -410,12 +513,18 @@ Either, you use a directory ".build" within the root path, or you separate "source" and "build" directories within the root path.''' do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n', boolean) - print ''' + if os.name == 'nt': + print ''' +Inside the root directory, two more directories will be created; "_templates" +for custom HTML templates and "_static" for custom stylesheets and other +static files. You can enter another prefix (such as ".") to replace the underscore.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) + else: + print ''' Inside the root directory, two more directories will be created; ".templates" for custom HTML templates and ".static" for custom stylesheets and other -static files. Since the leading dot may be inconvenient for Windows users, -you can enter another prefix (such as "_") to replace the dot.''' - do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) +static files. You can enter another prefix (such as "_") to replace the dot.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) print ''' The project name will occur in several places in the built documentation.''' @@ -454,6 +563,8 @@ only have to run e.g. `make html' instead of invoking sphinx-build directly.''' do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', os.name == 'posix' and 'y' or 'n', boolean) + do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', + os.name == 'nt' and 'y' or 'n', boolean) d['project_fn'] = make_filename(d['project']) d['now'] = time.asctime() @@ -505,12 +616,21 @@ directly.''' f.write((MAKEFILE % d).encode('utf-8')) f.close() + create_batch = d['batchfile'].upper() in ('Y', 'YES') + if create_batch: + d['rsrcdir'] = separate and 'source' or '.' + d['rbuilddir'] = separate and 'build' or d['dot'] + 'build' + f = open(path.join(d['path'], 'make.bat'), 'w') + f.write((BATCHFILE % d).encode('utf-8')) + f.close() + + print print bold('Finished: An initial directory structure has been created.') print ''' You should now populate your master file %s and create other documentation source files. Use the sphinx-build script to build the docs, like so: -''' % masterfile + (create_makefile and ''' +''' % masterfile + ((create_makefile or create_batch) and ''' make ''' or ''' sphinx-build -b %s %s -- cgit v1.2.1 From ccf4f7068170e90a4f8618c4dcf8cf54b424b1ca Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 13:38:39 +0100 Subject: The new ``html_show_sourcelink`` config value can be used to switch off the links to the reST sources in the sidebar. --- sphinx/quickstart.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sphinx/quickstart.py') diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 1f076575..91213f32 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -165,8 +165,8 @@ html_static_path = ['%(dot)sstatic'] # If true, the index is split into individual pages for each letter. #html_split_index = False -# If true, the reST sources are included in the HTML build as _sources/. -#html_copy_source = True +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the -- cgit v1.2.1 From 864ef748749dca37a68e626a59e1bb48b8c704f0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 27 Dec 2008 12:19:17 +0100 Subject: Explicitly refer to the license in :license: tags. --- sphinx/quickstart.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sphinx/quickstart.py') diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 91213f32..8c5ffa3d 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -6,7 +6,7 @@ Quickly setup documentation source to work with Sphinx. :copyright: 2008 by Georg Brandl. - :license: BSD. + :license: BSD, see LICENSE for details. """ import sys, os, time -- cgit v1.2.1 From 86cc3d89a3882c70fc707895c834106915bd5db4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 00:51:51 +0100 Subject: New builder for Qt help collections, by Antonio Valentino. (This is not finished work yet.) --- sphinx/quickstart.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'sphinx/quickstart.py') diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 8c5ffa3d..ab0a2094 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -257,7 +257,7 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html web pickle htmlhelp latex changes linkcheck +.PHONY: help clean html pickle json htmlhelp qthelp latex changes linkcheck help: \t@echo "Please use \\`make ' where is one of" @@ -265,6 +265,7 @@ help: \t@echo " pickle to make pickle files" \t@echo " json to make JSON files" \t@echo " htmlhelp to make HTML files and a HTML help project" +\t@echo " qthelp to make HTML files and a qthelp project" \t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" \t@echo " changes to make an overview over all changed/added/deprecated items" \t@echo " linkcheck to check all external links for integrity" @@ -284,8 +285,6 @@ pickle: \t@echo \t@echo "Build finished; now you can process the pickle files." -web: pickle - json: \tmkdir -p %(rbuilddir)s/json %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) %(rbuilddir)s/json @@ -299,6 +298,16 @@ htmlhelp: \t@echo "Build finished; now you can run HTML Help Workshop with the" \\ \t ".hhp project file in %(rbuilddir)s/htmlhelp." +qthelp: +\tmkdir -p %(rbuilddir)s/qthelp %(rbuilddir)s/doctrees +\t$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) %(rbuilddir)s/qthelp +\t@echo +\t@echo "Build finished; now you can run "qcollectiongenerator" with the" \\ +\t ".qhcp project file in %(rbuilddir)s/qthelp, like this:" +\t@echo "# qcollectiongenerator %(rbuilddir)s/qthelp/Sphinx.qhcp" +\t@echo "To view the help file:" +\t@echo "# assistant -collectionFile %(rbuilddir)s/qthelp/%(project)s.qhc" + latex: \tmkdir -p %(rbuilddir)s/latex %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) %(rbuilddir)s/latex -- cgit v1.2.1