diff --git a/doc/Makefile b/doc/Makefile index 9db48fd4a2e08c9f2a063ec850c96b8317f91a76..b9adacb70898e0ec265ebb296c3ee334a730c549 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -37,6 +37,11 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +html-noplot: + $(SPHINXBUILD) -D plot_gallery=False -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo diff --git a/doc/README b/doc/README index e0a8ae37c588b8820905215fe35379353bf6a290..840e8b043a26c60e0f0f1b17d3aab6a61c0b0dc6 100644 --- a/doc/README +++ b/doc/README @@ -1,3 +1,29 @@ +Documentation for scikits.learn +------------------------------- + +This section contains the full manual and web page as displayed in +http://scikit-learn.sf.net. To generate the full web page, including +the example gallery (this might take a while): + + + make html + +Or, if you'd rather not build the example gallery: + + make html-noplot + +That should create all the doc in directory _build/html + +To build the pdf manual, you should first make the latex docs: + + make latex + +and then: + + cd _build/latex + make all-pdf + + Upload the generated doc to sourceforge --------------------------------------- @@ -5,7 +31,7 @@ First of, generate the html documentation:: make html -This should create a directory _build/html with the documentation in html fornmat. +This should create a directory _build/html with the documentation in html fornmat. Now can upload the generated html documentation using scp or some other SFTP clients. diff --git a/doc/conf.py b/doc/conf.py index ceb2f7adc16fe71729c75f4d4eafe4164a56e665..e7d98f6084013d114b388530b461f7a2871049be 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -45,6 +45,9 @@ source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8' +# Generate the plots for the gallery +plot_gallery = True + # The master toctree document. master_doc = 'index' @@ -57,7 +60,7 @@ copyright = u'2010, scikits.learn developers' # built documents. # # The short X.Y version. -version = '0.5' +version = '0.6' # The full version, including alpha/beta/rc tags. release = '0.6-git' diff --git a/doc/sphinxext/gen_rst.py b/doc/sphinxext/gen_rst.py index b575bf8d878c762d2cf236dabb86244c6afde8f8..eb65d573c4a81181f2ca44f75f7b240dfbdb8690 100644 --- a/doc/sphinxext/gen_rst.py +++ b/doc/sphinxext/gen_rst.py @@ -80,6 +80,10 @@ def generate_example_rst(app): """ root_dir = os.path.join(app.builder.srcdir, 'auto_examples') example_dir = os.path.abspath(app.builder.srcdir + '/../' + 'examples') + try: + plot_gallery = eval(app.builder.config.plot_gallery) + except TypeError: + plot_gallery = bool(app.builder.config.plot_gallery) if not os.path.exists(example_dir): os.makedirs(example_dir) if not os.path.exists(root_dir): @@ -99,16 +103,16 @@ Examples """) # Here we don't use an os.walk, but we recurse only twice: flat is # better than nested. - generate_dir_rst('.', fhindex, example_dir, root_dir) + generate_dir_rst('.', fhindex, example_dir, root_dir, plot_gallery) for dir in sorted(os.listdir(example_dir)): if dir == '.svn': continue if os.path.isdir(os.path.join(example_dir, dir)): - generate_dir_rst(dir, fhindex, example_dir, root_dir) + generate_dir_rst(dir, fhindex, example_dir, root_dir, plot_gallery) fhindex.flush() -def generate_dir_rst(dir, fhindex, example_dir, root_dir): +def generate_dir_rst(dir, fhindex, example_dir, root_dir, plot_gallery): """ Generate the rst file for an example directory. """ target_dir = os.path.join(root_dir, dir) @@ -127,11 +131,11 @@ def generate_dir_rst(dir, fhindex, example_dir, root_dir): os.makedirs(target_dir) for fname in sorted(os.listdir(src_dir)): if fname.endswith('py'): - generate_file_rst(fname, target_dir, src_dir) + generate_file_rst(fname, target_dir, src_dir, plot_gallery) fhindex.write(' %s\n' % (os.path.join(dir, fname[:-3]))) -def generate_file_rst(fname, target_dir, src_dir): +def generate_file_rst(fname, target_dir, src_dir, plot_gallery): """ Generate the rst file for a given example. """ image_name = fname[:-2] + 'png' @@ -145,7 +149,7 @@ def generate_file_rst(fname, target_dir, src_dir): src_file = os.path.join(src_dir, fname) example_file = os.path.join(target_dir, fname) shutil.copyfile(src_file, example_file) - if fname.startswith('plot'): + if plot_gallery and fname.startswith('plot'): # generate the plot as png image if file name # starts with plot and if it is more recent than an # existing image. @@ -178,4 +182,4 @@ def generate_file_rst(fname, target_dir, src_dir): def setup(app): app.connect('builder-inited', generate_example_rst) - + app.add_config_value('plot_gallery', True, 'html')