Repository files navigation

This is a template for usingSphinxandSphinx-Galleryto document a Python package with examples. It includes:

• a sample package (SampleModule) with two modules:
  • module.py which defines an example class and an example function
  • data_download.py which provides functions for downloading largedatasets required for examples and storing the path to the downloadeddatasets to ensure that they are only downloaded once
• two galleries of examples that demonstrate Sphinx-Gallery functions
• a way to automatically build the documentation whenever the repository ispushed to

1. Clone this repository:

   git clone https://github.com/sphinx-gallery/sample-project.git

2. Update theSampleModule to include your package modules instead
3. Update thedocs/conf.py with your project details in this section:

   # -- Project information -----------------------------------------------------project = 'sample-project'copyright = '2020, <Author>'author = '<Author>'# The full version, including alpha/beta/rc tagsrelease = '0.0.1'

   and desired gallery configurations in this section:

   # sphinx-gallery configurationsphinx_gallery_conf = {    # path to your example scripts    'examples_dirs': ['../sample-gallery-1', '../sample-gallery-2'],    # path to where to save gallery generated output    'gallery_dirs': ['auto_gallery-1', 'auto_gallery-2'],    # specify that examples should be ordered according to filename    'within_subsection_order': FileNameSortKey,    # directory where function granular galleries are stored    'backreferences_dir': 'gen_modules/backreferences',    # Modules for which function level galleries are created.  In    # this case sphinx_gallery and numpy in a tuple of strings.    'doc_module': ('SampleModule'),}

4. Updatesample-gallery-1 andsample-gallery-2 to your own examplegalleries. Use the command:

   $ make html

   from the directorydocs/ to build the documentation and see the effects ofyour changes to the example.py files.

For full configuration options seeSphinx documentation andSphinx-Gallery documentaton

If your examples require datasets (especially if the same dataset is usedacross several examples), you may wish to use the functionsdefined inSampleModule/data_download.py to download the required datasetsduring building of the documentation. Thedownload_data function first checksif the data file already exists in either the path saved under the keydata_key in the config file or the default data path;~/sg_template_data. If the file does not exist, it downloads the datafromurl argument given and saves to a filename specified in the argumentdata_file_name. Finally, it also stores the location of the data in aconfiguration file, under keydata_key. Seesample-gallery-1/plot_1_download_data.py for an example of the function inuse.

The following projects use a similar method to make datasets available whenbuilding their examples and can be looked to for guidance, especially if yourproject has specific data needs:

• MNE-python, specificallydataset/utils
• scikit-learn, specificallydatasets/_base

Configuration templates are provided for usingCircleCIandGithub actions to automaticallybuild your documentation after every push. This allows you to view changesin the built documentation and be informed of any errors during building.

Both options are discussed in detail below to help you decide which is moresuitable for your project.

To use CircleCI in your project, first follow their sign up stepshere. The.circleci/config.ymlfile outlines a simple workflow that builds the documentation and storesit as an artifact after every push. If you wish to make changes to the workflow,seeCircleCI configurationto learn how to amend the.circleci/config.yml foryour project needs. Additionally, to enable CircleCI builds on forkedpull requests, follow the stepshere.

A handy link to the buit documentation is also added to Github via theGithub actioncircleci-artifacts-redirector,via the configuration file.github/workflows/main.yml.

The workflow stored at.github/workflows/sphinx_build.yml uses the communityactionSphinx build actionto build the documentation. The Github actionupload artifactis then used to store the built documentation. The built documentation canbe downloaded by navigating to the 'Actions' tab of the repository but notbe directly viewed online like with CircleCI. There are alsolimitations on how long the artifact is stored, seehere formore details. Additonally, if you wish to make changes to the workflow seehereto learn how to amend the.github/workflows/sphinx_build.yml file for yourproject needs.

Finally, it may be useful toenable debug loggingto aid in diagnosing why your workflow is not working.