Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4fa8f41

Browse files
jklymakjklymak
committed
ENH: allow rst files to pass through
1 parent a71d62d commit 4fa8f41

File tree

18 files changed

+402
-97
lines changed

18 files changed

+402
-97
lines changed

‎doc/configuration.rst‎

Lines changed: 46 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -409,14 +409,14 @@ point to the directory containing ``searchindex.js``, such as
409409
If you wish to do the same for ordinary RST documentation,
410410
see :ref:`plain_rst`.
411411

412-
If you are using inheritance for your documented code and you are experience
413-
wrong links in the sense that the links point to the base class of an object
414-
instead of the child, the option ``prefer_full_module`` might solve your issue.
415-
Have also a look at `the GitHub
412+
If you are using inheritance for your documented code and you are experience
413+
wrong links in the sense that the links point to the base class of an object
414+
instead of the child, the option ``prefer_full_module`` might solve your issue.
415+
Have also a look at `the GitHub
416416
issue <https://github.com/sphinx-gallery/sphinx-gallery/issues/947>`__
417417
implementing this option for more context.
418418

419-
To make this work in your documentation you need to include to the
419+
To make this work in your documentation you need to include to the
420420
configuration
421421
dictionary within your Sphinx ``conf.py`` file::
422422

@@ -429,8 +429,8 @@ dictionary within your Sphinx ``conf.py`` file::
429429
]
430430
}
431431

432-
In the above examples all modules matching the string ``'yourmodule.*+\d{4}'``
433-
would use the full module name when creating the links. All other use the
432+
In the above examples all modules matching the string ``'yourmodule.*+\d{4}'``
433+
would use the full module name when creating the links. All other use the
434434
(default) way of linking.
435435

436436
.. _references_to_examples:
@@ -1865,6 +1865,44 @@ each subsection, and a specific toctree for each subsection.
18651865
In particular, sidebars generated using these toctrees might not reflect the
18661866
actual section / folder structure.
18671867

1868+
.. _manual_passthrough:
1869+
1870+
Manually passing files
1871+
======================
1872+
1873+
By default, Sphinx-Gallery creates all the files that are written in the
1874+
sphinx-build directory, either by generating rst and images from a ``*.py``
1875+
in the gallery-source, or from creating ``index.rst`` from ``README.txt``
1876+
in the gallery-source. However, sometimes it is desirable to pass files
1877+
from the gallery-source to the sphinx-build. For example, you may want
1878+
to pass an image that a gallery refers to, but does not generate itself.
1879+
You may also want to pass raw rst from the gallery-source to the
1880+
sphinx-build, because that material fits in thematically with your gallery,
1881+
but is easier to write as rst. To accomodate this, you may set
1882+
``copyfile_regex`` in ``sphinx_gallery_conf``. The following copies
1883+
across rst files.
1884+
1885+
.. code-block:: python
1886+
1887+
sphinx_gallery_conf = {
1888+
...
1889+
'copyfile_regex': r'.*\.rst',
1890+
}
1891+
1892+
Note that if you copy across files rst files, for instance, it is your
1893+
responsibility to ensure that they are in a sphinx ``toctree`` somewhere
1894+
in your document. You can, of course, add a ``toctree`` to your
1895+
``README.txt``.
1896+
1897+
Manually passing ``index.rst``
1898+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1899+
1900+
If you want control over the gallery (or subgallery) ``index.rst``, you
1901+
can bypass Sphinx-Gallery creating it from ``README.txt`` by including
1902+
it in the gallery-source instead of the README. If you do this, you are
1903+
responsible for building your own ``toctree`` in that index or elsewhere
1904+
that includes the gallery items.
1905+
18681906
.. _show_api_usage:
18691907

18701908
Showing API Usage
@@ -1884,7 +1922,7 @@ are used in. This could be helpful for making a map of which examples to
18841922
look at if you want to learn about a particular module. Setting
18851923
``show_api_usage`` to ``False`` will not make any graphs or documentation
18861924
about API usage. Note, ``graphviz`` is required for making the unused and
1887-
used API entry graphs.
1925+
used API entry graphs.
18881926

18891927
.. _api_usage_ignore:
18901928

‎sphinx_gallery/gen_gallery.py‎

Lines changed: 100 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ def __call__(self, gallery_conf, script_vars):
104104
'prefer_full_module': [],
105105
'api_usage_ignore': '.*__.*__',
106106
'show_api_usage': False,
107+
'copyfile_regex': None,
107108
}
108109

109110
logger = sphinx.util.logging.getLogger('sphinx-gallery')
@@ -481,7 +482,6 @@ def generate_gallery_rst(app):
481482
check_spaces_in_filenames(files)
482483

483484
for examples_dir, gallery_dir in workdirs:
484-
485485
examples_dir_abs_path = os.path.join(app.builder.srcdir, examples_dir)
486486
gallery_dir_abs_path = os.path.join(app.builder.srcdir, gallery_dir)
487487

@@ -505,81 +505,84 @@ def generate_gallery_rst(app):
505505
costs += this_costs
506506
write_computation_times(gallery_conf, gallery_dir_abs_path, this_costs)
507507

508-
# We create an index.rst with all examples
509-
# (this will overwrite the rst file generated by the previous call
510-
# to generate_dir_rst)
511-
index_rst_new = os.path.join(gallery_dir_abs_path, 'index.rst.new')
512-
with codecs.open(index_rst_new, 'w', encoding='utf-8') as fhindex:
513-
# :orphan: to suppress "not included in TOCTREE" sphinx warnings
514-
fhindex.write(":orphan:\n\n" + this_content)
515-
516-
# Write toctree with gallery items from gallery root folder
517-
if len(this_toctree_items) > 0:
518-
this_toctree = """
508+
if this_content:
509+
510+
# We create an index.rst with all examples
511+
# (this will overwrite the rst file generated by the previous call
512+
# to generate_dir_rst)
513+
index_rst_new = os.path.join(gallery_dir_abs_path, 'index.rst.new')
514+
with codecs.open(index_rst_new, 'w', encoding='utf-8') as fhindex:
515+
# :orphan: to suppress "not included in TOCTREE" sphinx
516+
# warnings
517+
fhindex.write(":orphan:\n\n" + this_content)
518+
519+
# Write toctree with gallery items from gallery root folder
520+
if len(this_toctree_items) > 0:
521+
this_toctree = """
519522
.. toctree::
520523
:hidden:
521524
522525
%s\n
523526
""" % "\n ".join(this_toctree_items)
524-
fhindex.write(this_toctree)
525-
526-
# list all paths to subsection index files in this array
527-
subsection_index_files = []
528-
529-
for subsection in get_subsections(
530-
app.builder.srcdir, examples_dir_abs_path, gallery_conf):
531-
src_dir = os.path.join(examples_dir_abs_path, subsection)
532-
target_dir = os.path.join(gallery_dir_abs_path, subsection)
533-
subsection_index_files.append(
534-
'/'.join([
535-
'', gallery_dir, subsection, 'index.rst'
536-
]).replace(os.sep, '/') # fwd slashes needed inside rst
537-
)
538-
539-
(
540-
subsection_index_path,
541-
subsection_index_content,
542-
subsection_costs,
543-
subsection_toctree_filenames,
544-
) = generate_dir_rst(
545-
src_dir, target_dir, gallery_conf, seen_backrefs
546-
)
547-
548-
# Filter out tags from subsection content
549-
# to prevent tag duplication across the documentation
550-
tag_regex = r"^\.\.(\s+)\_(.+)\:(\s*)$"
551-
subsection_index_content = "\n".join([
552-
line for line in subsection_index_content.splitlines()
553-
if re.match(tag_regex, line) is None
554-
] + [''])
555-
556-
fhindex.write(subsection_index_content)
557-
558-
# Write subsection toctree in main file only if
559-
# nested_sections is False or None, and
560-
# toctree filenames were generated for the subsection.
561-
if not gallery_conf["nested_sections"]:
562-
if len(subsection_toctree_filenames) > 0:
563-
subsection_index_toctree = """
527+
fhindex.write(this_toctree)
528+
529+
# list all paths to subsection index files in this array
530+
subsection_index_files = []
531+
subsecs = get_subsections(app.builder.srcdir,
532+
examples_dir_abs_path, gallery_conf)
533+
for subsection in subsecs:
534+
src_dir = os.path.join(examples_dir_abs_path, subsection)
535+
target_dir = os.path.join(gallery_dir_abs_path, subsection)
536+
subsection_index_files.append(
537+
'/'.join([
538+
'', gallery_dir, subsection, 'index.rst'
539+
]).replace(os.sep, '/') # fwd slashes needed in rst
540+
)
541+
542+
(
543+
subsection_index_path,
544+
subsection_index_content,
545+
subsection_costs,
546+
subsection_toctree_filenames,
547+
) = generate_dir_rst(
548+
src_dir, target_dir, gallery_conf, seen_backrefs
549+
)
550+
551+
# Filter out tags from subsection content
552+
# to prevent tag duplication across the documentation
553+
tag_regex = r"^\.\.(\s+)\_(.+)\:(\s*)$"
554+
subsection_index_content = "\n".join([
555+
line for line in subsection_index_content.splitlines()
556+
if re.match(tag_regex, line) is None
557+
] + [''])
558+
559+
fhindex.write(subsection_index_content)
560+
561+
# Write subsection toctree in main file only if
562+
# nested_sections is False or None, and
563+
# toctree filenames were generated for the subsection.
564+
if not gallery_conf["nested_sections"]:
565+
if len(subsection_toctree_filenames) > 0:
566+
subsection_index_toctree = """
564567
.. toctree::
565568
:hidden:
566569
567570
%s\n
568571
""" % "\n ".join(subsection_toctree_filenames)
569-
fhindex.write(subsection_index_toctree)
570-
# Otherwise, a new index.rst.new file should
571-
# have been created and it needs to be parsed
572-
else:
573-
_replace_md5(subsection_index_path, mode='t')
572+
fhindex.write(subsection_index_toctree)
573+
# Otherwise, a new index.rst.new file should
574+
# have been created and it needs to be parsed
575+
else:
576+
_replace_md5(subsection_index_path, mode='t')
574577

575-
costs += subsection_costs
576-
write_computation_times(
577-
gallery_conf, target_dir, subsection_costs
578-
)
578+
costs += subsection_costs
579+
write_computation_times(
580+
gallery_conf, target_dir, subsection_costs
581+
)
579582

580-
# generate toctree with subsections
581-
if gallery_conf["nested_sections"] is True:
582-
subsections_toctree = """
583+
# generate toctree with subsections
584+
if gallery_conf["nested_sections"] is True:
585+
subsections_toctree = """
583586
.. toctree::
584587
:hidden:
585588
:includehidden:
@@ -588,20 +591,42 @@ def generate_gallery_rst(app):
588591
""" % "\n ".join(subsection_index_files)
589592
# """ % "\n ".join(this_toctree_items + subsection_index_files)
590593

591-
# add toctree to file only if there are subsections
592-
if len(subsection_index_files) > 0:
593-
fhindex.write(subsections_toctree)
594+
# add toctree to file only if there are subsections
595+
if len(subsection_index_files) > 0:
596+
fhindex.write(subsections_toctree)
594597

595-
if gallery_conf['download_all_examples']:
596-
download_fhindex = generate_zipfiles(
597-
gallery_dir_abs_path, app.builder.srcdir
598-
)
599-
fhindex.write(download_fhindex)
598+
if gallery_conf['download_all_examples']:
599+
download_fhindex = generate_zipfiles(
600+
gallery_dir_abs_path, app.builder.srcdir
601+
)
602+
fhindex.write(download_fhindex)
600603

601-
if (app.config.sphinx_gallery_conf['show_signature']):
602-
fhindex.write(SPHX_GLR_SIG)
604+
if (app.config.sphinx_gallery_conf['show_signature']):
605+
fhindex.write(SPHX_GLR_SIG)
606+
607+
_replace_md5(index_rst_new, mode='t')
608+
else:
609+
# we still need to check each subfolder and generate any
610+
# galleries, but we don't need to make the rst for the top level.
611+
subsecs = [subfolder for subfolder in
612+
os.listdir(examples_dir_abs_path)]
613+
subsecs = [os.path.basename(s) for s in subsecs if
614+
os.path.isdir(os.path.join(examples_dir_abs_path, s))]
615+
for subsection in subsecs:
616+
src_dir = os.path.join(examples_dir_abs_path, subsection)
617+
target_dir = os.path.join(gallery_dir_abs_path, subsection)
618+
(
619+
subsection_index_path,
620+
subsection_index_content,
621+
subsection_costs,
622+
subsection_toctree_filenames,
623+
) = generate_dir_rst(
624+
src_dir, target_dir, gallery_conf, seen_backrefs
625+
)
626+
if (gallery_conf["nested_sections"] and
627+
subsection_index_content):
628+
_replace_md5(subsection_index_path, mode='t')
603629

604-
_replace_md5(index_rst_new, mode='t')
605630
if gallery_conf['show_api_usage'] is not False:
606631
init_api_usage(app.builder.srcdir)
607632
_finalize_backreferences(seen_backrefs, gallery_conf)

‎sphinx_gallery/gen_rst.py‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -335,6 +335,11 @@ def save_thumbnail(image_path_template, src_file, script_vars, file_conf,
335335

336336

337337
def _get_readme(dir_, gallery_conf, raise_error=True):
338+
# first check if there is an index.rst:
339+
fpth = os.path.join(dir_, 'index.rst')
340+
if os.path.isfile(fpth):
341+
return None
342+
# now look for README.txt, README.rst etc...
338343
extensions = ['.txt'] + sorted(gallery_conf['app'].config['source_suffix'])
339344
for ext in extensions:
340345
for fname in ('README', 'readme'):
@@ -393,10 +398,14 @@ def generate_dir_rst(
393398

394399
subsection_index_content = ""
395400
subsection_readme_fname = _get_readme(src_dir, gallery_conf)
396-
397-
with codecs.open(subsection_readme_fname, 'r', encoding='utf-8') as fid:
398-
subsection_readme_content = fid.read()
399-
subsection_index_content += subsection_readme_content
401+
have_index_rst = False
402+
if subsection_readme_fname:
403+
with codecs.open(subsection_readme_fname,
404+
'r', encoding='utf-8') as fid:
405+
subsection_readme_content = fid.read()
406+
subsection_index_content += subsection_readme_content
407+
else:
408+
have_index_rst = True
400409

401410
# Add empty lines to avoid bug in issue #165
402411
subsection_index_content += "\n\n"
@@ -477,6 +486,25 @@ def generate_dir_rst(
477486
""" % "\n ".join(subsection_toctree_filenames)
478487
findex.write(subsection_index_toctree)
479488

489+
if have_index_rst:
490+
# the user has supplied index.rst, so blank out the content
491+
subsection_index_content = None
492+
493+
# Copy over any other files.
494+
copyregex = gallery_conf.get('copyfile_regex')
495+
if copyregex:
496+
listdir = [fname for fname in os.listdir(src_dir) if
497+
re.match(copyregex, fname)]
498+
readme = _get_readme(src_dir, gallery_conf, raise_error=False)
499+
# don't copy over the readme
500+
if readme:
501+
listdir = [fname for fname in listdir if
502+
fname != os.path.basename(readme)]
503+
for fname in listdir:
504+
src_file = os.path.normpath(os.path.join(src_dir, fname))
505+
target_file = os.path.join(target_dir, fname)
506+
_replace_md5(src_file, fname_old=target_file, method='copy')
507+
480508
return (
481509
subsection_index_path,
482510
subsection_index_content,

0 commit comments

Comments
 (0)