.. note::
    :class: sphx-glr-download-link-note

    Click :ref:`here <sphx_glr_download_auto_examples_conf.py>` to download the full example code
.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_conf.py:

Sphinx config file
==================

config source code


.. code-block:: default


    #
    # Configuration file for the Sphinx documentation builder.
    #
    # This file does only contain a selection of the most common options. For a
    # full list see the documentation:
    # http://www.sphinx-doc.org/en/master/config

    # -- Path setup --------------------------------------------------------------

    # If extensions (or modules to document with autodoc) are in another directory,
    # add these directories to sys.path here. If the directory is relative to the
    # documentation root, use os.path.abspath to make it absolute, like shown here.
    #
    # import os
    # import sys
    # sys.path.insert(0, os.path.abspath('.'))









.. code-block:: default

    from __future__ import print_function
    import os
    import sys
    import shutil
    import subprocess








.. code-block:: default


    # -- Project information -----------------------------------------------------

    project = u'Doc tutorial'
    copyright = u'2019, nobody'
    author = u'nobody'

    # The short X.Y version
    version = u''
    # The full version, including alpha/beta/rc tags
    release = u'1.0.0'


    # -- General configuration ---------------------------------------------------

    # If your documentation needs a minimal Sphinx version, state it here.
    #
    # needs_sphinx = '1.0'

    # Add any Sphinx extension module names here, as strings. They can be
    # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
    # ones.
    extensions = [
        'sphinx.ext.autodoc',
        'sphinx.ext.doctest',
        'sphinx.ext.intersphinx',
        'sphinx.ext.todo',
        'sphinx.ext.coverage',
        'sphinx.ext.mathjax',
        'sphinx.ext.ifconfig',
        'sphinx.ext.viewcode',
        'sphinx.ext.githubpages',
        'sphinx.ext.napoleon',
        'sphinx.ext.extlinks',
        'sphinx.ext.inheritance_diagram',
    ]









.. code-block:: default


    # -- nbsphinx ext -------
    try:
        # nbsphinx converts ipython/jupyter notebooks to sphinx docs
        import nbsphinx
        import distutils.spawn
        if not distutils.spawn.find_executable('pandoc'):
            print('Warning: pandoc is missing. Notebooks will not be included '
                  'in the docs')
        else:
            nbsphinx_allow_errors = True
            extensions += ['nbsphinx',
                          'sphinx.ext.mathjax']
            # set this env variable to tell notebooks that we should not use
            # any GUI during notebooks execution
            os.environ['ALLOW_GUI'] = '0'
            print('-- nbsphinx should work. --')
    except ImportError as e:
        nbsphinx = None
        print('Warning: nbsphinx could not be imported, the notebooks will not '
              'appear in the docs')

    # -- sphinx-gallery ext -----
    try:
        import matplotlib
        import sphinx_gallery
        extensions.append('sphinx_gallery.gen_gallery')
        sphinx_gallery_conf = {
            'examples_dirs': 'code_examples',   # path to your example scripts
            'gallery_dirs': 'auto_examples',  # path where to save gallery generated examples
            'filename_pattern': '.*\.py',
            #'ignore_pattern': r'/[^abcefgmnst][^/]*\.py$',
            'expected_failing_examples': ['code_examples/conf.py'],
        }
    except ImportError:
        pass  # no gallery. Oh, well.




.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    -- nbsphinx should work. --





.. code-block:: default


    # Add any paths that contain templates here, relative to this directory.
    templates_path = ['_templates']

    # The suffix(es) of source filenames.
    # You can specify multiple suffix as a list of string:
    #
    # source_suffix = ['.rst', '.md']
    source_suffix = '.rst'

    # The master toctree document.
    master_doc = 'index'

    # The language for content autogenerated by Sphinx. Refer to documentation
    # for a list of supported languages.
    #
    # This is also used if you do content translation via gettext catalogs.
    # Usually you set "language" from the command line for these cases.
    language = None

    # List of patterns, relative to source directory, that match files and
    # directories to ignore when looking for source files.
    # This pattern also affects html_static_path and html_extra_path.
    exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']

    # The name of the Pygments (syntax highlighting) style to use.
    pygments_style = None


    # -- Options for HTML output -------------------------------------------------

    # The theme to use for HTML and HTML Help pages.  See the documentation for
    # a list of builtin themes.
    #
    html_theme = 'alabaster'
    #html_theme = 'default'

    # Theme options are theme-specific and customize the look and feel of a theme
    # further.  For a list of options available for each theme, see the
    # documentation.
    #
    # html_theme_options = {}

    # Add any paths that contain custom static files (such as style sheets) here,
    # relative to this directory. They are copied after the builtin static files,
    # so a file named "default.css" will overwrite the builtin "default.css".
    html_static_path = ['_static']

    # Custom sidebar templates, must be a dictionary that maps document names
    # to template names.
    #
    # The default sidebars (for documents that don't match any pattern) are
    # defined by theme itself.  Builtin themes are using these templates by
    # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
    # 'searchbox.html']``.
    #
    # html_sidebars = {}


    # -- Options for HTMLHelp output ---------------------------------------------

    # Output file base name for HTML help builder.
    htmlhelp_basename = 'Doctutorialdoc'


    # -- Options for LaTeX output ------------------------------------------------

    latex_elements = {
        # The paper size ('letterpaper' or 'a4paper').
        #
        # 'papersize': 'letterpaper',

        # The font size ('10pt', '11pt' or '12pt').
        #
        # 'pointsize': '10pt',

        # Additional stuff for the LaTeX preamble.
        #
        # 'preamble': '',

        # Latex figure (float) alignment
        #
        # 'figure_align': 'htbp',
    }

    # Grouping the document tree into LaTeX files. List of tuples
    # (source start file, target name, title,
    #  author, documentclass [howto, manual, or own class]).
    latex_documents = [
        (master_doc, 'Doctutorial.tex', u'Doc tutorial Documentation',
         u'nobody', 'manual'),
    ]


    # -- Options for manual page output ------------------------------------------

    # One entry per manual page. List of tuples
    # (source start file, name, description, authors, manual section).
    man_pages = [
        (master_doc, 'doctutorial', u'Doc tutorial Documentation',
         [author], 1)
    ]


    # -- Options for Texinfo output ----------------------------------------------

    # Grouping the document tree into Texinfo files. List of tuples
    # (source start file, target name, title, author,
    #  dir menu entry, description, category)
    texinfo_documents = [
        (master_doc, 'Doctutorial', u'Doc tutorial Documentation',
         author, 'Doctutorial', 'One line description of project.',
         'Miscellaneous'),
    ]


    # -- Options for Epub output -------------------------------------------------

    # Bibliographic Dublin Core info.
    epub_title = project

    # The unique identifier of the text. This can be a ISBN number
    # or the project homepage.
    #
    # epub_identifier = ''

    # A unique identification for the text.
    #
    # epub_uid = ''

    # A list of files that should not be packed into the epub file.
    epub_exclude_files = ['search.html']


    # -- Extension configuration -------------------------------------------------

    # -- Options for intersphinx extension ---------------------------------------

    # Example configuration for intersphinx: refer to the Python standard library.
    intersphinx_mapping = {
        'https://docs.python.org/': None,
        'https://populse.github.io/capsul/': None,
        'https://matplotlib.org/': None}

    # -- Options for todo extension ----------------------------------------------

    # If true, `todo` and `todoList` produce output, else they produce nothing.
    todo_include_todos = True








code added after regular sphinx conf file
##########################################


.. code-block:: default


    # -- Extlinks ------
    extlinks = {
      'capsul': ('https://populse.github.io/capsul/%s',
        'capsul '),
    }

    # -- nbsphinx ------
    if nbsphinx:
        # Notebooks handling:
        #
        # Several problems are handled here:
        # 1. nbsphinx 0.4 does not read (ignores) notebooks in _static/
        #    For this reason we moved the NB to tutorial/
        # 2. nbsphinx 0.4 does not allow direct links to the .ipynb (for download)
        #    but replaces them with the converted HTML page.
        #    For this reason we duplicate the NB into _static/ where NB are not
        #    processed, and links not changed
        # 3. notebooks include kernel infoemation which does not necessarily match the
        #    running/installed python and jupyter kernels.
        #    For this reason we conbert them using pupyter nbconvert, forcing the
        #    kernel to the current running python version.
        # 4. sphinx does not copy image files not in _static/ into the build tree.
        #    So we copy them into the build tree.
        # 5. nbsphinx 0.4 messes up image links when the notebook is not in the root
        #    of the sphinx tree. Typically in a notebook placed in tutorial/,
        #    containing links to "images/something.jpg", the HTML page will contain
        #    links to "tutorial/images/something.jpg".
        #    To overcome this, we copy the images directory into
        #    "tutorial/tutorial/images/" in the build tree.
        #
        # Thus, in git sources we have:
        #
        #     tutorial/capsul_tutorial.ipynb.in
        #     tutorial/images/*.jpg
        #
        # After running this conf.py (run by sphinx actually), we have additionally,
        # still in sources:
        #
        #     tutorial/capsul_tutorial.ipynb
        #
        # and in the build tree:
        #
        #     _static/tutorial/capsul_tutorial.ipynb
        #     tutorial/tutorial/images/*.jpg
        #
        # Hack to copy files from sources to build dir
        out_dir = sys.argv[-1]
        src_dir = sys.argv[-2]
        print('source:', src_dir)
        print('dest:', out_dir)
        print('cwd:', os.getcwd())
        #if not os.path.isabs(src_dir) and not os.path.exists(os.path.join(src_dir)):
            ## this strange config appears in Makefile builds
            #src_dir = os.getcwd()
        src_dir = os.path.abspath(src_dir)
        out_dir = os.path.join(os.path.abspath(out_dir), 'html')  # add html here
        print('abs source:', src_dir)
        print('abs dest:', out_dir)
        # nbsphinx 3/4 has a bug: it adds the 1st directory level to images paths.
        # so we have to move it into a 2nd level of 'tutorial'. Probably nbsphinx
        # is only working well for notebooks at the root of the source tree.
        out_tuto_path = os.path.join(out_dir, 'tutorial')
        out_tuto_img_path = os.path.join(out_tuto_path, 'tutorial')
        if os.path.exists(out_tuto_img_path):
            shutil.rmtree(out_tuto_img_path)
        if not os.path.exists(out_tuto_path):
            os.makedirs(out_tuto_path)
        if os.path.exists(os.path.join(src_dir, 'tutorial/images')):
            shutil.copytree(os.path.join(src_dir, 'tutorial/images'),
                            out_tuto_img_path)

        # convert notebook(s) with correct python kernel
        nb_name = 'sample_notebook.ipynb'
        in_nb = os.path.join(src_dir, 'tutorial/%s.in' % nb_name)
        out_nb = os.path.join(src_dir, 'tutorial/%s' % nb_name)
        args = [sys.executable, '-m', 'jupyter', 'nbconvert', '--to', 'notebook',
                '--execute',
                '--ExecutePreprocessor.kernel_name=python%d' % sys.version_info[0],
                '--output', out_nb, in_nb]
        print('exec:', *args)
        subprocess.check_call(args)

        #shutil.copy2(os.path.join(src_dir, 'tutorial/capsul_tutorial.ipynb.in'),
                    #os.path.join(out_tuto_path, 'capsul_tutorial.ipynb.in'))
        if not os.path.exists(os.path.join(out_dir, '_static/tutorial')):
            os.makedirs(os.path.join(out_dir, '_static/tutorial'))
        shutil.copy2(os.path.join(src_dir, 'tutorial/%s' % nb_name),
                    os.path.join(out_dir, '_static/tutorial/%s' % nb_name))

    # -- copy this conf.py as code example
    with open(os.path.join(src_dir, 'code_examples', 'conf.py'), 'w') as f:
        print('''"""Sphinx config file
    ==================

    config source code
    """
    ''', file=f)
        with open(__file__) as sf:
            next(iter(sf))  # skip encoding line
            for line in sf:
                f.write(line)

    # -- generate pipeline and processes docs -----
    # we must actually write in sources for now.
    sphinx_dir = os.path.dirname(__file__)
    proc_rst_dir = os.path.join(sphinx_dir, 'process_docs', 'example_module')
    if not os.path.exists(proc_rst_dir):
        os.makedirs(proc_rst_dir)
    cmd = [sys.executable, '-m', 'capsul.sphinxext.capsul_pipeline_rst',
           '-i', 'sample_module.capsul', '-o', proc_rst_dir, '--schema']
    print('generating CAPSUL processes docs...')
    print(cmd)
    subprocess.check_output(cmd)





.. code-block:: pytb

    Traceback (most recent call last):
      File "/home/travis/virtualenv/python3.7.1/lib/python3.7/site-packages/sphinx_gallery/gen_rst.py", line 440, in _memory_usage
        out = func()
      File "/home/travis/virtualenv/python3.7.1/lib/python3.7/site-packages/sphinx_gallery/gen_rst.py", line 425, in __call__
        exec(self.code, self.globals)
      File "/home/travis/build/denisri/demo-doc/doc/code_examples/conf.py", line 306, in <module>
        src_dir = sys.argv[-2]
    IndexError: list index out of range





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.007 seconds)


.. _sphx_glr_download_auto_examples_conf.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download

     :download:`Download Python source code: conf.py <conf.py>`



  .. container:: sphx-glr-download

     :download:`Download Jupyter notebook: conf.ipynb <conf.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_