Installing Sphinx on mac

Last week I installed Sphinx on my macOS computer to start practicing the document-making by Sphinx. I frequently see the documents of tools and others generated by Sphinx. I like the simple outlook and their well-structured formats  of the sphinx documents. It looks little a bit difficult to start using this tools for me, and I hesitated to introduce this application on my computer. Recently I found O'Reilly's book that seems good for learning Sphinx from scratch. I purchased the book and get started this tool for the first time.

Installation

In the text, there are good concise tutorials to install Sphinx on one's machine (Windows/macOS/Linux). In my case, just install sphinx using conda package manager. 

(base) tk$ conda install -c conda-forge sphinx

Collecting package metadata (current_repodata.json): done

Solving environment: done

## Package Plan ##

  environment location: /Path/to/miniconda3

  added / updated specs:

    - sphinx

The following packages will be downloaded:

    package                    |            build

    ---------------------------|-----------------

    alabaster-0.7.13           |     pyhd8ed1ab_0          18 KB  conda-forge

    docutils-0.19              |  py310h2ec42d9_1         761 KB  conda-forge

    imagesize-1.4.1            |     pyhd8ed1ab_0          10 KB  conda-forge

    snowballstemmer-2.2.0      |     pyhd8ed1ab_0          57 KB  conda-forge

    sphinx-6.1.3               |     pyhd8ed1ab_0         1.2 MB  conda-forge

    sphinxcontrib-applehelp-1.0.4|     pyhd8ed1ab_0          29 KB  conda-forge

    sphinxcontrib-devhelp-1.0.2|             py_0          22 KB  conda-forge

    sphinxcontrib-htmlhelp-2.0.1|     pyhd8ed1ab_0          32 KB  conda-forge

    sphinxcontrib-jsmath-1.0.1 |             py_0           7 KB  conda-forge

    sphinxcontrib-qthelp-1.0.3 |             py_0          25 KB  conda-forge

    sphinxcontrib-serializinghtml-1.1.5|     pyhd8ed1ab_2          27 KB  conda-forge

    ------------------------------------------------------------

                                           Total:         2.1 MB

The following NEW packages will be INSTALLED:

  alabaster          conda-forge/noarch::alabaster-0.7.13-pyhd8ed1ab_0 

  docutils           conda-forge/osx-64::docutils-0.19-py310h2ec42d9_1 

  imagesize          conda-forge/noarch::imagesize-1.4.1-pyhd8ed1ab_0 

  snowballstemmer    conda-forge/noarch::snowballstemmer-2.2.0-pyhd8ed1ab_0 

  sphinx             conda-forge/noarch::sphinx-6.1.3-pyhd8ed1ab_0 

  sphinxcontrib-app~ conda-forge/noarch::sphinxcontrib-applehelp-1.0.4-pyhd8ed1ab_0 

  sphinxcontrib-dev~ conda-forge/noarch::sphinxcontrib-devhelp-1.0.2-py_0 

  sphinxcontrib-htm~ conda-forge/noarch::sphinxcontrib-htmlhelp-2.0.1-pyhd8ed1ab_0 

  sphinxcontrib-jsm~ conda-forge/noarch::sphinxcontrib-jsmath-1.0.1-py_0 

  sphinxcontrib-qth~ conda-forge/noarch::sphinxcontrib-qthelp-1.0.3-py_0 

  sphinxcontrib-ser~ conda-forge/noarch::sphinxcontrib-serializinghtml-1.1.5-pyhd8ed1ab_2 

Proceed ([y]/n)? y

After installation, I checked by,

(base) tk$ sphinx-quickstart --version

sphinx-quickstart 6.1.3

I successfully installed sphinx on my system.

References

Sphinxをはじめよう 第3版 O'REILLY Japan: https://www.oreilly.co.jp/books/9784873119830/
Support page:  https://github.com/getstart-sphinx/getstart-sphinx

Useful jupyter lab extension: jupyterlab_templates

 I daily use the jupyter lab for data analysis workflow. Recently I updated the jupyter lab and I found that the jupyterlab extension manager can be available. Since then I frequently check the jupyterlab extension to make my jupyter environment more useful and productive. 

Jupyterlab Extension Manager -- T.Y. Blog

 There are some stuffs I always use in the notebook such as description markdown cells and import-modules cells for notebooks. Today I found an extension for jupyterlab that seems useful for setting up templates.

Jupyterlab_template

Support for jupyter notebook templates in jupyterlab

The readme can be available from the github page.

https://github.com/finos/jupyterlab_templates#readme

Installation

Installation guide is available in github README.md. Since I use conda for package management, I install jupyterlab_templates using  conda install , 

(base) tk$ conda install -c conda-forge jupyterlab_templates

Retrieving notices: ...working... done

Collecting package metadata (current_repodata.json): done

Solving environment: done

## Package Plan ##

  environment location: /Path/to/miniconda3

  added / updated specs:

    - jupyterlab_templates

The following packages will be downloaded:

    package                    |            build

    ---------------------------|-----------------

    jupyterlab_templates-0.3.2 |     pyh1d7be83_0          72 KB  conda-forge

    ------------------------------------------------------------

                                           Total:          72 KB

The following NEW packages will be INSTALLED:

  jupyterlab_templa~ conda-forge/noarch::jupyterlab_templates-0.3.2-pyh1d7be83_0 

Proceed ([y]/n)? y

Then I install jupyterlab_templates on Extension Manager,

Configuration file

Next, adding parameters on  jupyter_notebook_config.py  is necessary to let jupyterlab find the template files in  template_dirs . The jupyter_notebook_config.py is a configration file of jupyterlab. If there is no file on your system yet, it can be generated by

(base) tk$ jupyter lab --generate-config

Writing default config to: /Path/to/home/.jupyter/jupyter_lab_config.py

I edited this file on the terminal to add three lines below,

c.JupyterLabTemplates.template_dirs = ['/Path/to/template/directory']

c.JupyterLabTemplates.include_default = True

c.JupyterLabTemplates.include_core_paths = True

^G Get Help       ^O WriteOut       ^R Read File      ^Y Prev Pg        ^K Cut Text       ^C Cur Pos        

^X Exit           ^J Justify        ^W Where is       ^V Next Pg        ^U UnCut Text     ^T To Spell       

Now the setup of this extension was completed.

Using template from Launcher

I restart the jupyter lab and found the template button was added on Launcher.

Then The preparation of jupyterlab_extension was completed. When clicking the "Template" on Notebook, I can choose the ipynb template on template directory.

Note that the updates of template directories and notebooks are not reflected until the system is once restarted. 

References

1. https://github.com/finos/jupyterlab_templates

2. https://qiita.com/taka4sato/items/2c3397ff34c440044978

3. https://qiita.com/sky_jokerxx/items/d77d674955e57d71b9f5

4. https://xtreme-d.net/news-techblog-1031/

5. https://jupyter-notebook.readthedocs.io/en/stable/config.html

Jupyterlab Extension Manager

Extension manager is enable from jupyterlab

 Recently I updated the jupyter lab on my personal computer after a long time since the last execution. 

(base) tk$ conda update conda

Now my version of jupyter lab is 3.5.2. Before that the version was very older one and not a few stuff have been changed on the current version. Especially I found that the Extension manager available in the left of the window. 

Wow! 

I clicked the Enable button and many options available were shown.

It's quite easy to find the extensions from the list and inspect them. Click the blue links and I can open their Github pages. 

Kite is saying farewell

For example I searched Kite autocomplete extension using search box,

https://github.com/kiteco/jupyterlab-kite

I clicked the 'Install' button and the message below was shown,

hmm, OK. 

(base) tk$ pip install jupyter-kite

Collecting jupyterlab-kite

  Downloading jupyterlab-kite-2.0.2.tar.gz (266 kB)

and I got an error message...

Oh, I see...

base) tk$ conda install -c conda-forge nodejs

Collecting package metadata (current_repodata.json): done

Solving environment: done

## Package Plan ##

  environment location: /path/to/my/home/miniconda3

  added / updated specs:

    - nodejs

The following packages will be downloaded:

    package                    |            build

    ---------------------------|-----------------

    libuv-1.44.2               |       hac89ed1_0         441 KB  conda-forge

    nodejs-18.13.0             |       hd0c9b3c_0        10.3 MB  conda-forge

    ------------------------------------------------------------

                                           Total:        10.8 MB

The following NEW packages will be INSTALLED:

  libuv              conda-forge/osx-64::libuv-1.44.2-hac89ed1_0 

  nodejs             conda-forge/osx-64::nodejs-18.13.0-hd0c9b3c_0 

and I retry the installation.

I restart jupyterlab, and I got the message,

The icon of Kite was shown, but I could not use Kite. I clicked the Fix This button,  and found the message below...!

Kite is saying farewell

From 2014 to 2021, Kite was a startup using AI to help developers write code. We have stopped working on Kite, and are no longer supporting the Kite software.

Thank you to everyone who used our product, and thank you to our team members and investors who made this journey possible.

https://www.kite.com/blog/product/kite-is-saying-farewell/

Hmm... is this the reason I could not use Kite on jupyterlab??

I could not fix this problem, but I finished trying to install this extension...

(base) tk$ pip uninstall jupyterlab-kite

Found existing installation: jupyterlab-kite 2.0.2

Uninstalling jupyterlab-kite-2.0.2:

jupyterlab-cell-flash

I tried different jupyterlab extension. 

https://github.com/jupyterlab-contrib/jupyterlab-cell-flash

Looks nice! This extension works well :-)

Jupyterlab documentation:

https://jupyterlab.readthedocs.io/en/stable/user/extensions.html#managing-extensions-with-jupyter-labextension