diff --git a/doc/configuration.rst b/doc/configuration.rst index 58014db15..603c915b8 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -60,6 +60,7 @@ file: - ``nested_sections`` (:ref:`nested_sections`) - ``api_usage_ignore`` (:ref:`api_usage_ignore`) - ``show_api_usage`` (:ref:`show_api_usage`) +- ``copyfile_regex`` (:ref:`manual_passthrough`) Some options can also be set or overridden on a file-by-file basis: @@ -409,14 +410,14 @@ point to the directory containing ``searchindex.js``, such as If you wish to do the same for ordinary RST documentation, see :ref:`plain_rst`. -If you are using inheritance for your documented code and you are experience -wrong links in the sense that the links point to the base class of an object -instead of the child, the option ``prefer_full_module`` might solve your issue. -Have also a look at `the GitHub +If you are using inheritance for your documented code and you are experience +wrong links in the sense that the links point to the base class of an object +instead of the child, the option ``prefer_full_module`` might solve your issue. +Have also a look at `the GitHub issue `__ implementing this option for more context. -To make this work in your documentation you need to include to the +To make this work in your documentation you need to include to the configuration dictionary within your Sphinx ``conf.py`` file:: @@ -429,8 +430,8 @@ dictionary within your Sphinx ``conf.py`` file:: ] } -In the above examples all modules matching the string ``'yourmodule.*+\d{4}'`` -would use the full module name when creating the links. All other use the +In the above examples all modules matching the string ``'yourmodule.*+\d{4}'`` +would use the full module name when creating the links. All other use the (default) way of linking. .. _references_to_examples: @@ -1865,6 +1866,47 @@ each subsection, and a specific toctree for each subsection. In particular, sidebars generated using these toctrees might not reflect the actual section / folder structure. +.. _manual_passthrough: + +Manually passing files +====================== + +By default, Sphinx-Gallery creates all the files that are written in the +sphinx-build directory, either by generating rst and images from a ``*.py`` +in the gallery-source, or from creating ``index.rst`` from ``README.txt`` +in the gallery-source. However, sometimes it is desirable to pass files +from the gallery-source to the sphinx-build. For example, you may want +to pass an image that a gallery refers to, but does not generate itself. +You may also want to pass raw rst from the gallery-source to the +sphinx-build, because that material fits in thematically with your gallery, +but is easier to write as rst. To accomodate this, you may set +``copyfile_regex`` in ``sphinx_gallery_conf``. The following copies +across rst files. + +.. code-block:: python + + sphinx_gallery_conf = { + ... + 'copyfile_regex': r'.*\.rst', + } + +Note that if you copy across files rst files, for instance, it is your +responsibility to ensure that they are in a sphinx ``toctree`` somewhere +in your document. You can, of course, add a ``toctree`` to your +``README.txt``. + +Manually passing ``index.rst`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can bypass Sphinx-Gallery automatically creating an ``index.rst`` from a +``README.txt`` in a gallery directory or subdirectory. If your +``copyfile_regex`` includes ``index.rst``, and you have an ``index.rst`` in the +gallery-source instead of the README, Sphinx-Gallery will use that instead of +the index it automatically makes. If you do this, you are responsible for +adding your own Sphinx ``toctree`` in that index (or elsewhere in your Sphinx +documentation) that includes any gallery items or other files in that +directory. + .. _show_api_usage: Showing API Usage @@ -1884,7 +1926,7 @@ are used in. This could be helpful for making a map of which examples to look at if you want to learn about a particular module. Setting ``show_api_usage`` to ``False`` will not make any graphs or documentation about API usage. Note, ``graphviz`` is required for making the unused and -used API entry graphs. +used API entry graphs. .. _api_usage_ignore: diff --git a/sphinx_gallery/gen_gallery.py b/sphinx_gallery/gen_gallery.py index 5ffc62aa0..25ee2789c 100644 --- a/sphinx_gallery/gen_gallery.py +++ b/sphinx_gallery/gen_gallery.py @@ -104,6 +104,7 @@ def __call__(self, gallery_conf, script_vars): 'prefer_full_module': [], 'api_usage_ignore': '.*__.*__', 'show_api_usage': False, + 'copyfile_regex': '', } logger = sphinx.util.logging.getLogger('sphinx-gallery') @@ -397,7 +398,7 @@ def call_memory(func): return gallery_conf -def get_subsections(srcdir, examples_dir, gallery_conf): +def get_subsections(srcdir, examples_dir, gallery_conf, check_for_index=True): """Return the list of subsections of a gallery. Parameters @@ -408,6 +409,8 @@ def get_subsections(srcdir, examples_dir, gallery_conf): path to the examples directory relative to conf.py gallery_conf : dict The gallery configuration. + check_for_index : bool + only return subfolders with a ReadMe, default True Returns ------- @@ -415,9 +418,16 @@ def get_subsections(srcdir, examples_dir, gallery_conf): sorted list of gallery subsection folder names """ sortkey = gallery_conf['subsection_order'] - subfolders = [subfolder for subfolder in os.listdir(examples_dir) - if _get_readme(os.path.join(examples_dir, subfolder), - gallery_conf, raise_error=False) is not None] + subfolders = [subfolder for subfolder in os.listdir(examples_dir)] + if check_for_index: + subfolders = [subfolder for subfolder in subfolders + if _get_readme(os.path.join(examples_dir, subfolder), + gallery_conf, raise_error=False) + is not None] + else: + # just make sure its a directory + subfolders = [subfolder for subfolder in subfolders + if os.path.isdir(os.path.join(examples_dir, subfolder))] base_examples_dir_path = os.path.relpath(examples_dir, srcdir) subfolders_with_path = [os.path.join(base_examples_dir_path, item) for item in subfolders] @@ -447,6 +457,24 @@ def _prepare_sphx_glr_dirs(gallery_conf, srcdir): return list(zip(examples_dirs, gallery_dirs)) +def _format_toctree(items, includehidden=False): + """Format a toc tree""" + + st = """ +.. toctree:: + :hidden: +""" + if includehidden: + st += """ + :includehidden: +""" + st += """ + + %s\n""" % "\n ".join(items) + + return st + + def generate_gallery_rst(app): """Generate the Main examples gallery reStructuredText @@ -481,7 +509,6 @@ def generate_gallery_rst(app): check_spaces_in_filenames(files) for examples_dir, gallery_dir in workdirs: - examples_dir_abs_path = os.path.join(app.builder.srcdir, examples_dir) gallery_dir_abs_path = os.path.join(app.builder.srcdir, gallery_dir) @@ -502,49 +529,52 @@ def generate_gallery_rst(app): include_toctree=False, ) + has_readme = this_content is not None costs += this_costs write_computation_times(gallery_conf, gallery_dir_abs_path, this_costs) # We create an index.rst with all examples # (this will overwrite the rst file generated by the previous call # to generate_dir_rst) - index_rst_new = os.path.join(gallery_dir_abs_path, 'index.rst.new') - with codecs.open(index_rst_new, 'w', encoding='utf-8') as fhindex: - # :orphan: to suppress "not included in TOCTREE" sphinx warnings - fhindex.write(":orphan:\n\n" + this_content) - - # Write toctree with gallery items from gallery root folder - if len(this_toctree_items) > 0: - this_toctree = """ -.. toctree:: - :hidden: - - %s\n -""" % "\n ".join(this_toctree_items) - fhindex.write(this_toctree) - - # list all paths to subsection index files in this array - subsection_index_files = [] - - for subsection in get_subsections( - app.builder.srcdir, examples_dir_abs_path, gallery_conf): - src_dir = os.path.join(examples_dir_abs_path, subsection) - target_dir = os.path.join(gallery_dir_abs_path, subsection) - subsection_index_files.append( - '/'.join([ - '', gallery_dir, subsection, 'index.rst' - ]).replace(os.sep, '/') # fwd slashes needed inside rst - ) - - ( - subsection_index_path, - subsection_index_content, - subsection_costs, - subsection_toctree_filenames, - ) = generate_dir_rst( - src_dir, target_dir, gallery_conf, seen_backrefs - ) + if this_content: + # :orphan: to suppress "not included in TOCTREE" sphinx warnings + indexst = ":orphan:\n\n" + this_content + else: + # we are not going to use the index.rst.new that gets made here, + # but go through the motions to run through all the subsections... + indexst = 'Never used!' + + # Write toctree with gallery items from gallery root folder + if len(this_toctree_items) > 0: + this_toctree = _format_toctree(this_toctree_items) + + indexst += this_toctree + + # list all paths to subsection index files in this array + subsection_index_files = [] + subsecs = get_subsections(app.builder.srcdir, + examples_dir_abs_path, gallery_conf, + check_for_index=has_readme) + for subsection in subsecs: + src_dir = os.path.join(examples_dir_abs_path, subsection) + target_dir = os.path.join(gallery_dir_abs_path, subsection) + subsection_index_files.append( + '/'.join([ + '', gallery_dir, subsection, 'index.rst' + ]).replace(os.sep, '/') # fwd slashes needed in rst + ) + + ( + subsection_index_path, + subsection_index_content, + subsection_costs, + subsection_toctree_filenames, + ) = generate_dir_rst( + src_dir, target_dir, gallery_conf, seen_backrefs + ) + + if subsection_index_content: # Filter out tags from subsection content # to prevent tag duplication across the documentation tag_regex = r"^\.\.(\s+)\_(.+)\:(\s*)$" @@ -553,55 +583,50 @@ def generate_gallery_rst(app): if re.match(tag_regex, line) is None ] + ['']) - fhindex.write(subsection_index_content) - - # Write subsection toctree in main file only if - # nested_sections is False or None, and - # toctree filenames were generated for the subsection. - if not gallery_conf["nested_sections"]: - if len(subsection_toctree_filenames) > 0: - subsection_index_toctree = """ -.. toctree:: - :hidden: - - %s\n -""" % "\n ".join(subsection_toctree_filenames) - fhindex.write(subsection_index_toctree) - # Otherwise, a new index.rst.new file should - # have been created and it needs to be parsed - else: - _replace_md5(subsection_index_path, mode='t') - - costs += subsection_costs - write_computation_times( - gallery_conf, target_dir, subsection_costs - ) - - # generate toctree with subsections - if gallery_conf["nested_sections"] is True: - subsections_toctree = """ -.. toctree:: - :hidden: - :includehidden: - - %s\n -""" % "\n ".join(subsection_index_files) -# """ % "\n ".join(this_toctree_items + subsection_index_files) - - # add toctree to file only if there are subsections - if len(subsection_index_files) > 0: - fhindex.write(subsections_toctree) - - if gallery_conf['download_all_examples']: - download_fhindex = generate_zipfiles( - gallery_dir_abs_path, app.builder.srcdir - ) - fhindex.write(download_fhindex) - - if (app.config.sphinx_gallery_conf['show_signature']): - fhindex.write(SPHX_GLR_SIG) + indexst += subsection_index_content + + # Write subsection toctree in main file only if + # nested_sections is False or None, and + # toctree filenames were generated for the subsection. + if not gallery_conf["nested_sections"]: + if len(subsection_toctree_filenames) > 0: + subsection_index_toctree = _format_toctree( + subsection_toctree_filenames) + indexst += subsection_index_toctree + # Otherwise, a new index.rst.new file should + # have been created and it needs to be parsed + elif has_readme: + _replace_md5(subsection_index_path, mode='t') + + costs += subsection_costs + write_computation_times( + gallery_conf, target_dir, subsection_costs + ) + + # generate toctree with subsections + if gallery_conf["nested_sections"] is True: + subsections_toctree = _format_toctree( + subsection_index_files, includehidden=True) + + # add toctree to file only if there are subsections + if len(subsection_index_files) > 0: + indexst += subsections_toctree + + if gallery_conf['download_all_examples']: + download_fhindex = generate_zipfiles( + gallery_dir_abs_path, app.builder.srcdir + ) + indexst += download_fhindex + + if (app.config.sphinx_gallery_conf['show_signature']): + indexst += SPHX_GLR_SIG + + if has_readme: + index_rst_new = os.path.join(gallery_dir_abs_path, 'index.rst.new') + with codecs.open(index_rst_new, 'w', encoding='utf-8') as fhindex: + fhindex.write(indexst) + _replace_md5(index_rst_new, mode='t') - _replace_md5(index_rst_new, mode='t') if gallery_conf['show_api_usage'] is not False: init_api_usage(app.builder.srcdir) _finalize_backreferences(seen_backrefs, gallery_conf) diff --git a/sphinx_gallery/gen_rst.py b/sphinx_gallery/gen_rst.py index cd352c37e..48c00dc49 100644 --- a/sphinx_gallery/gen_rst.py +++ b/sphinx_gallery/gen_rst.py @@ -335,6 +335,13 @@ def save_thumbnail(image_path_template, src_file, script_vars, file_conf, def _get_readme(dir_, gallery_conf, raise_error=True): + # first check if there is an index.rst and that index.rst is in the + # copyfile regexp: + if re.match(gallery_conf['copyfile_regex'], 'index.rst'): + fpth = os.path.join(dir_, 'index.rst') + if os.path.isfile(fpth): + return None + # now look for README.txt, README.rst etc... extensions = ['.txt'] + sorted(gallery_conf['app'].config['source_suffix']) for ext in extensions: for fname in ('README', 'readme'): @@ -393,10 +400,14 @@ def generate_dir_rst( subsection_index_content = "" subsection_readme_fname = _get_readme(src_dir, gallery_conf) - - with codecs.open(subsection_readme_fname, 'r', encoding='utf-8') as fid: - subsection_readme_content = fid.read() - subsection_index_content += subsection_readme_content + have_index_rst = False + if subsection_readme_fname: + with codecs.open(subsection_readme_fname, + 'r', encoding='utf-8') as fid: + subsection_readme_content = fid.read() + subsection_index_content += subsection_readme_content + else: + have_index_rst = True # Add empty lines to avoid bug in issue #165 subsection_index_content += "\n\n" @@ -451,7 +462,7 @@ def generate_dir_rst( # Write subsection index file # only if nested_sections is True subsection_index_path = None - if gallery_conf["nested_sections"] is True: + if gallery_conf["nested_sections"] is True and not have_index_rst: subsection_index_path = os.path.join(target_dir, 'index.rst.new') with codecs.open(subsection_index_path, 'w', encoding='utf-8') as ( findex @@ -477,6 +488,25 @@ def generate_dir_rst( """ % "\n ".join(subsection_toctree_filenames) findex.write(subsection_index_toctree) + if have_index_rst: + # the user has supplied index.rst, so blank out the content + subsection_index_content = None + + # Copy over any other files. + copyregex = gallery_conf.get('copyfile_regex') + if copyregex: + listdir = [fname for fname in os.listdir(src_dir) if + re.match(copyregex, fname)] + readme = _get_readme(src_dir, gallery_conf, raise_error=False) + # don't copy over the readme + if readme: + listdir = [fname for fname in listdir if + fname != os.path.basename(readme)] + for fname in listdir: + src_file = os.path.normpath(os.path.join(src_dir, fname)) + target_file = os.path.join(target_dir, fname) + _replace_md5(src_file, fname_old=target_file, method='copy') + return ( subsection_index_path, subsection_index_content, diff --git a/sphinx_gallery/tests/test_full.py b/sphinx_gallery/tests/test_full.py index 3d9c35e01..3d894e687 100644 --- a/sphinx_gallery/tests/test_full.py +++ b/sphinx_gallery/tests/test_full.py @@ -30,18 +30,20 @@ # total number of plot_*.py files in tinybuild/examples + examples_rst_index # + examples_with_rst -N_EXAMPLES = 13 +N_EXAMPLES = 13 + 3 + 2 N_FAILING = 2 N_GOOD = N_EXAMPLES - N_FAILING # galleries that run w/o error -# indices SG generates + examples/local_module (extra non-plot*.py file) +# passthroughs examples_rst_index, examples_with_rst +N_PASS = 0 + 2 +# indices SG generates (extra non-plot*.py file) # + examples_rst_index + examples_with_rst -N_INDEX = 2 + 1 +N_INDEX = 2 + 1 + 3 # SG execution times (example, + examples_rst_index + examples_with_rst) -N_EXECUTE = 2 -# gen_modules + index.rst + minigallery.rst + sg_api_usage -N_OTHER = 9 + 1 + 1 + 1 -N_RST = N_EXAMPLES + N_INDEX + N_EXECUTE + N_OTHER -N_RST = '(%s|%s)' % (N_RST, N_RST - 1) # AppVeyor weirdness +N_EXECUTE = 2 + 3 + 1 +# gen_modules + sg_api_usage + doc/index.rst + minigallery.rst +N_OTHER = 9 + 1 + 1 + 1 + 1 +N_RST = N_EXAMPLES + N_PASS + N_INDEX + N_EXECUTE + N_OTHER +N_RST = '(%s|%s|%s)' % (N_RST, N_RST - 1, N_RST - 2) # AppVeyor weirdness @pytest.fixture(scope='module') @@ -207,6 +209,8 @@ def test_run_sphinx(sphinx_app): out_files = os.listdir(out_dir) assert 'index.html' in out_files assert 'auto_examples' in out_files + assert 'auto_examples_with_rst' in out_files + assert 'auto_examples_rst_index' in out_files generated_examples_dir = op.join(out_dir, 'auto_examples') assert op.isdir(generated_examples_dir) status = sphinx_app._status.getvalue() @@ -718,7 +722,7 @@ def _rerun(how, src_dir, conf_dir, out_dir, toctrees_dir, # Windows: always 9 for some reason lines = [line for line in status.split('\n') if 'changed,' in line] lines = '\n'.join([how] + lines) - n_ch = '(7|8|9|10|11)' + n_ch = '(7|8|9|10|11|12)' want = f'.*updating environment:.*[0|1] added, {n_ch} changed, 0 removed.*' assert re.match(want, status, flags) is not None, lines want = ('.*executed 1 out of %s.*after excluding %s files.*based on MD5.*' diff --git a/sphinx_gallery/tests/tinybuild/doc/Makefile b/sphinx_gallery/tests/tinybuild/doc/Makefile index 72a3891b0..a8270ebe8 100644 --- a/sphinx_gallery/tests/tinybuild/doc/Makefile +++ b/sphinx_gallery/tests/tinybuild/doc/Makefile @@ -5,6 +5,8 @@ all: clean html show clean: rm -rf _build/* rm -rf auto_examples/ + rm -rf auto_examples_with_rst/ + rm -rf auto_examples_rst_index/ rm -rf gen_modules/ html: diff --git a/sphinx_gallery/tests/tinybuild/doc/conf.py b/sphinx_gallery/tests/tinybuild/doc/conf.py index 335d87fac..fae336400 100644 --- a/sphinx_gallery/tests/tinybuild/doc/conf.py +++ b/sphinx_gallery/tests/tinybuild/doc/conf.py @@ -84,10 +84,12 @@ def __call__(self, gallery_conf, fname): 'notebooks_dir': 'notebooks', 'use_jupyter_lab': True, }, - 'examples_dirs': ['../examples/'], + 'examples_dirs': ['../examples/', '../examples_with_rst/', + '../examples_rst_index'], 'reset_argv': ResetArgv(), 'reset_modules': (MockScrapeProblem(), 'matplotlib'), - 'gallery_dirs': ['auto_examples'], + 'gallery_dirs': ['auto_examples', 'auto_examples_with_rst', + 'auto_examples_rst_index'], 'backreferences_dir': 'gen_modules/backreferences', 'within_subsection_order': FileNameSortKey, 'image_scrapers': (matplotlib_format_scraper(),), @@ -103,6 +105,7 @@ def __call__(self, gallery_conf, fname): 'image_srcset': ["2x"], 'exclude_implicit_doc': ['figure_rst'], 'show_api_usage': True, + 'copyfile_regex': r'.*\.rst', } nitpicky = True highlight_language = 'python3' diff --git a/sphinx_gallery/tests/tinybuild/doc/index.rst b/sphinx_gallery/tests/tinybuild/doc/index.rst index 28afc2ced..b607dae16 100644 --- a/sphinx_gallery/tests/tinybuild/doc/index.rst +++ b/sphinx_gallery/tests/tinybuild/doc/index.rst @@ -36,3 +36,5 @@ This tests that mini-gallery reference labels work: :maxdepth: 2 auto_examples/index.rst + auto_examples_with_rst/index.rst + auto_examples_rst_index/index.rst diff --git a/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir1/README.txt b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir1/README.txt new file mode 100644 index 000000000..3aa73ae9d --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir1/README.txt @@ -0,0 +1,9 @@ +================================== +Example of directory with a README +================================== + +This subdir uses a README to generate the index. + +.. toctree:: + + plot_sub1 diff --git a/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir1/plot_sub1.py b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir1/plot_sub1.py new file mode 100644 index 000000000..a93962caf --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir1/plot_sub1.py @@ -0,0 +1,19 @@ +# -*- coding: utf-8 -*- +""" +Plot-sin sub1 +============= + +This is a file generated from ``plot_sub1.py`` by sphinx-gallery. +""" + +import numpy as np +import matplotlib.pyplot as plt + +x = np.linspace(0, 2 * np.pi, 100) +y = np.sin(x) + +plt.plot(x, y) +plt.xlabel(r'$x$') +plt.ylabel(r'$\sin(x)$') +# To avoid matplotlib text output +plt.show() diff --git a/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir2/index.rst b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir2/index.rst new file mode 100644 index 000000000..f8f6a22fa --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir2/index.rst @@ -0,0 +1,9 @@ +=============================== +Subdirectory2 with an index.rst +=============================== + +Here we need to specify any files in this directory in the toc by hand: + +.. toctree:: + + plot_sub2 \ No newline at end of file diff --git a/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir2/plot_sub2.py b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir2/plot_sub2.py new file mode 100644 index 000000000..29c71ef0e --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_rst_index/examp_subdir2/plot_sub2.py @@ -0,0 +1,18 @@ +# -*- coding: utf-8 -*- +""" +Plot-sin subdir 2 +================= + +""" + +import numpy as np +import matplotlib.pyplot as plt + +x = np.linspace(0, 2 * np.pi, 100) +y = np.sin(x) + +plt.plot(x, y) +plt.xlabel(r'$x$') +plt.ylabel(r'$\sin(x)$') +# To avoid matplotlib text output +plt.show() diff --git a/sphinx_gallery/tests/tinybuild/examples_rst_index/index.rst b/sphinx_gallery/tests/tinybuild/examples_rst_index/index.rst new file mode 100644 index 000000000..d7e7126f1 --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_rst_index/index.rst @@ -0,0 +1,26 @@ +========================================== +Example gallery that has its own index.rst +========================================== + +Usually made by sphinx-gallery from the ``README.txt``. +However, if ``index.rst`` is given, we use that instead and +ignore README.txt. + +.. toctree:: + + plot_examp + +Subtopic one +============ +.. toctree:: + + examp_subdir1/index + +Subtopic two +============ + +This subtopic's directory has its own index.rst. + +.. toctree:: + + examp_subdir2/index \ No newline at end of file diff --git a/sphinx_gallery/tests/tinybuild/examples_rst_index/plot_examp.py b/sphinx_gallery/tests/tinybuild/examples_rst_index/plot_examp.py new file mode 100644 index 000000000..9727a5148 --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_rst_index/plot_examp.py @@ -0,0 +1,18 @@ +# -*- coding: utf-8 -*- +""" +Introductory example - Plotting sin +=================================== + +""" + +import numpy as np +import matplotlib.pyplot as plt + +x = np.linspace(0, 2 * np.pi, 100) +y = np.sin(x) + +plt.plot(x, y) +plt.xlabel(r'$x$') +plt.ylabel(r'$\sin(x)$') +# To avoid matplotlib text output +plt.show() diff --git a/sphinx_gallery/tests/tinybuild/examples_with_rst/README.txt b/sphinx_gallery/tests/tinybuild/examples_with_rst/README.txt new file mode 100644 index 000000000..14c90a5b3 --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_with_rst/README.txt @@ -0,0 +1,39 @@ +===================================== +Example with rst files passed through +===================================== + +Sometimes it is desirable to mix rst files with python files in the same example +directory. Here, the source directory has a mix of python examples (``plot_boo.py``) +and raw rst files (``rst_example1.rst``). The rst files are passed directly from +the source directory ``/examples_with_rst/rst_example1.rst`` to the +directory created by ``sphinx-gallery`` in +``/doc/examples_with_rst/rst_example1.rst`` without change. + +Any rst files that are passed through this way must have a manual +``toctree`` entry somewhere, or you will get a warning that the file doesn't exist in +the toctree. We add that here to the ``README.txt`` as:: + + Rst files + ========= + + .. toctree:: + + rst_example1 + rst_example2 + + Sphinx-gallery files + ==================== + + +Note that the python example also shows up as a usual thumbnail below this table of contents. + +Rst files +========= + +.. toctree:: + + rst_example1 + rst_example2 + +Sphinx-gallery files +==================== \ No newline at end of file diff --git a/sphinx_gallery/tests/tinybuild/examples_with_rst/plot_boo.py b/sphinx_gallery/tests/tinybuild/examples_with_rst/plot_boo.py new file mode 100644 index 000000000..d017cfc3e --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_with_rst/plot_boo.py @@ -0,0 +1,21 @@ +# -*- coding: utf-8 -*- +""" +Plot a sin +========== + +Example of sin + +""" + + +import numpy as np +import matplotlib.pyplot as plt + +x = np.linspace(0, 2 * np.pi, 100) +y = np.sin(x) + +plt.plot(x, y) +plt.xlabel(r'$x$') +plt.ylabel(r'$\sin(x)$') +# To avoid matplotlib text output +plt.show() diff --git a/sphinx_gallery/tests/tinybuild/examples_with_rst/plot_cos.py b/sphinx_gallery/tests/tinybuild/examples_with_rst/plot_cos.py new file mode 100644 index 000000000..7553ec9fc --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_with_rst/plot_cos.py @@ -0,0 +1,19 @@ +# -*- coding: utf-8 -*- +""" +Plot-cos +======== + +""" + + +import numpy as np +import matplotlib.pyplot as plt + +x = np.linspace(0, 2 * np.pi, 100) +y = np.cos(x) + +plt.plot(x, y) +plt.xlabel(r'$x$') +plt.ylabel(r'$\sin(x)$') +# To avoid matplotlib text output +plt.show() diff --git a/sphinx_gallery/tests/tinybuild/examples_with_rst/rst_example1.rst b/sphinx_gallery/tests/tinybuild/examples_with_rst/rst_example1.rst new file mode 100644 index 000000000..a23a4c78c --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_with_rst/rst_example1.rst @@ -0,0 +1,13 @@ +======================== +A Restructured-text file +======================== + +This Rst file is passed through without being changed. It was in the source +directory as ``/examples_with_rst/rst_example1.rst`` and gets passed to the +directory created by ``sphinx-gallery`` in +``/doc/examples_with_rst/rst_example1.rst``. + +You need to reference this rst file in a *toctree* somewhere in your project, as +``sphinx-gallery`` will not add it to a *toctree* automatically like it +does for ``*.py`` examples. This could be referenced in your +``README.txt`` as we have done in this directory. \ No newline at end of file diff --git a/sphinx_gallery/tests/tinybuild/examples_with_rst/rst_example2.rst b/sphinx_gallery/tests/tinybuild/examples_with_rst/rst_example2.rst new file mode 100644 index 000000000..840c10eb5 --- /dev/null +++ b/sphinx_gallery/tests/tinybuild/examples_with_rst/rst_example2.rst @@ -0,0 +1,13 @@ +=============================== +A Second Restructured-text file +=============================== + +This Rst file is passed through without being changed. It was in the source +directory as ``/examples_with_rst/rst_example2.rst`` and gets passed to the +directory created by ``sphinx-gallery`` in +``/doc/examples_with_rst/rst_example2.rst``. + +You need to reference this rst file in a *toctree* somewhere in your project, as +``sphinx-gallery`` will not add it to a *toctree* automatically like it +does for ``*.py`` examples. This could be referenced in your +``README.txt`` as we have done in this directory. \ No newline at end of file