:orphan:

|rss_image|  **sphinx - 1/2** :ref:`==> <ap-cat-sphinx-1>` :ref:`Blog <ap-main-0>` :ref:`notebook (8) <ap-cat-notebook-0>` :ref:`sphinx (13) <ap-cat-sphinx-0>`

.. |rss_image| image:: feed-icon-16x16.png
    :target: ../_downloads/rss.xml
    :alt: RSS

----


.. index:: sphinx


.. _ap-cat-sphinx-0:

sphinx - 1/2
++++++++++++

.. blogpostagg::
    :title: Issue with sphinx and pybind11
    :date: 2020-08-10
    :keywords: sphinx,pybind11
    :categories: sphinx
    :rawfile: 2020/2020-08-10_pybind11_sphinx.rst

    The kind of nightmare I don't like spending time on:
    `[Regression] KeyError on pybind11-generated wrappers with Sphinx 3.2
    <https://github.com/sphinx-doc/sphinx/issues/8084>`_.




.. blogpostagg::
    :title: Check RST syntax
    :date: 2018-04-21
    :keywords: sphinx,RST
    :categories: sphinx
    :rawfile: 2018/2018-04-21_compile_rst.rst

    It is usually a pain to discover I made an error in a
    formula while I'm writing documentation. It fails
    quite long after after the unit tests started. The
    documentation is generated after the unit test pass.
    I also use a lot ``.. runpython::``
    (see :class:`RunPythonDirective <pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonDirective>`)
    to run pieces of code inside the documentation.
    It is quite annoying to discover it fails long after.
    So I creates a unit test which can be used to compile a
    single page of the documentation :
    `test_doc_page <https://github.com/sdpython/pyquickhelper/blob/master/_unittests/ut_module/test_doc_page.py>`_.
    I modify the page name when I have some doubt or I move to
    another one.




.. blogpostagg::
    :title: Long names on Windows
    :date: 2018-03-26
    :keywords: sphinx,gallery
    :categories: sphinx
    :rawfile: 2018/2018-03-26_gallery.rst

    One of my unit test was failing due to a weird
    error in :epkg:`sphinx-gallery`. The module could not
    write a file on :epkg:`Windows` because its name was longer
    than 260 which still seems to be a limit of the system.
    

    ...




.. blogpostagg::
    :title: Sphinx extensions in pyquickhelper
    :date: 2016-04-04
    :keywords: sharenet,custom role,role,custom directive,directive,bigger,runpython,blog post
    :categories: sphinx
    :rawfile: 2016/2016-04-04_sphinx_extension.rst

    Sphinx extensions implemented were move to a dedicated subfolder *sphinxext*:
    

    ...




.. blogpostagg::
    :title: Share buttons on a page from the documenation.
    :date: 2016-02-14
    :keywords: sharenet,custom role,role,custom directive,directive
    :categories: sphinx
    :rawfile: 2016/2016-02-14_sharenet.rst

    pyquickhelper now includes a directive and a role to share
    a page from the documentation on networks.
    See :class:`ShareNetDirective <pyquickhelper.sphinxext.sphinx_sharenet_extension.ShareNetDirective>`
    and :func:`sharenet_role <pyquickhelper.sphinxext.sphinx_sharenet_extension.sharenet_role>`.
    The syntax is the following::
    

    ...




.. blogpostagg::
    :title: Bigger text in the documentation
    :date: 2016-02-14
    :keywords: bigger,custom role,role
    :categories: sphinx
    :rawfile: 2016/2016-02-14_bigger.rst

    pyquickhelper now includes a role *bigger* which
    make a text :bigger:`bigger` ::
    

    ...




.. blogpostagg::
    :title: Sphinx extensions
    :date: 2015-12-12
    :keywords: sphinx,extensions
    :categories: sphinx
    :rawfile: 2015/2015-12-12_sphinx_extensions.rst

    The following repository
    `birkenfeld/sphinx-contrib/ <https://github.com/sphinx-contrib/legacy>`_
    contains many useful extensions
    to improve the rendering of
    `Sphinx <http://sphinx-doc.org/>`_ documentation:
    

    ...




.. blogpostagg::
    :title: Python code to generate part of sphinx documentation
    :date: 2015-12-12
    :keywords: sphinx,extensions,runpython
    :categories: sphinx
    :rawfile: 2015/2015-12-18_runpython.rst

    I used the same title as a question asked on stackoverflow:
    `Python code to generate part of sphinx documentation, is it possible? <http://stackoverflow.com/questions/7250659/python-code-to-generate-part-of-sphinx-documentation-is-it-possible>`_.
    It became the following
    :class:`RunPythonDirective <pyquickhelper.helpgen.sphinx_runpython_extension.RunPythonDirective>`
    which does the same with more options::
    

    ...




.. blogpostagg::
    :title: Local contents in Sphinx
    :date: 2015-12-05
    :keywords: sphinx,contents
    :categories: sphinx
    :rawfile: 2015/2015-12-05_local_content.rst

    The Sphinx command `contents <http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents>`_
    adds a table of contents to a page. As contents is pretty common,
    on the web, it is not always easy to search for it::
    

    ...




.. blogpostagg::
    :title: A few tips with Sphinx
    :date: 2015-10-10
    :keywords: sphinx,tips,latex,bullets
    :categories: sphinx,latex
    :rawfile: 2015/2015-10-10_tips_sphinx.rst

    Sphinx generates many warning when it builds
    the documentation despite the fact the result looks good.
    Some cases.
    

    ...





----

|rss_image|  **sphinx - 1/2** :ref:`==> <ap-cat-sphinx-1>` :ref:`2020-08 (2) <ap-month-2020-08-0>` :ref:`2020-09 (1) <ap-month-2020-09-0>` :ref:`2021-01 (1) <ap-month-2021-01-0>` :ref:`2022-03 (1) <ap-month-2022-03-0>` :ref:`2023-05 (1) <ap-month-2023-05-0>`