:orphan:

|rss_image|  **documentation - 1/2** :ref:`==> <ap-cat-documentation-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:: documentation


.. _ap-cat-documentation-0:

documentation - 1/2
+++++++++++++++++++

.. blogpostagg::
    :title: Issues with sphinx-gallery
    :date: 2017-08-25
    :keywords: documentation,sphinx,sphinx-gallery
    :categories: documentation
    :rawfile: 2017/2017-08-25_sphinxgallery.rst

    Taking another dependency always means a potential
    conflicts between version. Is it fact enough updated
    when it breaks? I realized I was not the only to face an
    issue with `sphinx-gallery <https://github.com/sphinx-gallery/sphinx-gallery>`_.
    There is a discussion about it on
    `scikit-learn/9189 <https://github.com/scikit-learn/scikit-learn/issues/9189>`_
    and the package is now included in the
    `sources <https://scikit-learn.org/stable/auto_examples/index.html>`_.
    It is not really bothering for a small package like this.
    But still, it is extra work.
    I realize open source holds on some kind of magic
    sometimes. Some are fun but keeping them alive
    takes some energy.




.. blogpostagg::
    :title: Pandoc on ubuntu and WSL
    :date: 2017-08-20
    :keywords: documentation,sphinx,pandoc
    :categories: documentation
    :rawfile: 2017/2017-08-20_pandoc.rst

    I was using the `Windows Subsystem for Linux <https://msdn.microsoft.com/en-us/commandline/wsl/about>`_
    to test a module with Linux. I could not make it work
    due to an old version of :epkg:`pandoc`.
    Surprisingly, the default ``apt-get install pandoc`` installed
    a very old version (1.12). I could not convert any notebook
    with `nbconvert <https://github.com/jupyter/nbconvert>`_ into latex.
    I finally installed the latest version (1.19) and it worked perfectly.
    You can see the installation step in file
    `.circleci/config.yml <https://github.com/sdpython/pyquickhelper/blob/master/.circleci/config.yml>`_.
    That was not the last issue because
    *pandoc* seems to be very slow on WSL.
    About that, you can read:
    `massive delay to call pandoc using the Windows Subsystem for Linux (WSL) or Bash for Windows <https://github.com/jgm/pandoc/issues/3448>`_,
    `stack ghc painfully slow <https://github.com/Microsoft/BashOnWindows/issues/1671>`_.




.. blogpostagg::
    :title: Bug in Sphinx 1.6.2 for custom css
    :date: 2017-06-05
    :keywords: documentation,sphinx,bug
    :categories: documentation
    :rawfile: 2017/2017-06-05_sphinx_bug_css.rst

    I was finally able to take some time and finish
    the migration to *Sphinx 1.6.2*. However,
    there is still an error I cannot fix because it
    is a bug in Sphinx which happens when a custom css is used.
    

    ...




.. blogpostagg::
    :title: Fixable issues with Sphinx 1.6.1
    :date: 2017-05-21
    :keywords: documentation,startup
    :categories: documentation
    :rawfile: 2017/2017-05-21_sphinx.rst

    `Sphinx <https://www.sphinx-doc.org/en/master/>`_
    has released a new version 1.6.1. Other packages
    updated their code but some issues remain.
    I had to modify the code of the file
    `sphinx/transforms/__init__.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/transforms/__init__.py>`_
    to propage the environment *env* if not present.
    

    ...




.. blogpostagg::
    :title: Issues with Sphinx 1.6.1
    :date: 2017-05-17
    :keywords: documentation,startup
    :categories: documentation
    :rawfile: 2017/2017-05-17_sphinx.rst

    `Sphinx <https://www.sphinx-doc.org/en/master/>`_
    has released a new version 1.6.1 but it breaks a couple of
    packages.
    `sphinx_gallery <https://sphinx-gallery.readthedocs.io/en/latest/>`_
    breaks with the following error:
    

    ...




.. blogpostagg::
    :title: Links to Sphinx extensions
    :date: 2016-11-19
    :keywords: sphinx
    :categories: documentation
    :rawfile: 2016/2016-11-19_sphinx_axesome.rst

    *Awesome* really became a good keyword to find references about anything:
    `Awesome Sphinx <https://github.com/yoloseem/awesome-sphinxdoc>`_.




.. blogpostagg::
    :title: Generate the documentation on Anaconda
    :date: 2016-08-27
    :keywords: documentation,Anaconda
    :categories: documentation
    :rawfile: 2016/2016-08-27_conda_and_documentation.rst

    On Anaconda, the documentation generation fails for
    two reasons. The first one is the current version of *Sphinx* *(1.4.1)*
    and *pyquickhelper* requires *>= 1.4.5*. After fixing it
    with *pip*, the following exception happens (only on Anaconda)
    on a virtual environment:
    

    ...




.. blogpostagg::
    :title: Make a reference to a blog post
    :date: 2016-06-11
    :keywords: reference
    :categories: documentation,example
    :rawfile: 2016/2016-06-11_blogpost_with_label.rst

    Make a reference to the label ``label-to-this-blogpost``
    to reference this blog post. Look at the source of this page
    to see how this id was specified.




.. blogpostagg::
    :title: Producing a version for Python 2.7 from Python 3
    :date: 2015-04-17
    :keywords: python 2.7,migration
    :categories: documentation,Python 2.7
    :rawfile: 2015/2015-04-17_ipython27.rst

    I tried to make most of the unit tests run under Python 2.7.
    Most of the function deals with strings for the documentation
    and it is a real pain to think again about
    str, `unicode <https://docs.python.org/2/howto/unicode.html>`_, bytes.
    Some of the functions only works in Python 3 but the goal
    was more to see what needed to be done.
    

    ...




.. blogpostagg::
    :title: Migration to IPython 3.1
    :date: 2015-04-16
    :keywords: ipython,migration,jupyter,jenkins,pandoc
    :categories: ipython,documentation
    :rawfile: 2015/2015-04-16_ipython3.rst

    It took me some time to do the migration to IPython 3.1.
    The code which automatically generates the documentation
    had to be updated to follow the new format of the notebooks.
    I had to redo the configuration of ipython
    to have the graph inline...
    I hope ipython does not rename itself into
    `jupyter <https://jupyter.org/>`_.
    The design is better but the notebooks crash from time to time.
    I guess the code becomes better each time a migration happens.
    But it takes quite some time.
    However, the changes are not reversible. Ipython needs to be updated
    otherwise the automated generation of the documentation will not work.
    For Jenkins, just remind that the server needs your credentials
    othewise it does not easily find
    `pandoc <http://pandoc.org/>`_.





----

|rss_image|  **documentation - 1/2** :ref:`==> <ap-cat-documentation-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>`