Learnings from Setting up Sphinx [Jan 21, 2022]

(properly for the first time)

This file is to chronicle stuff I learnt from setting up this website and might forget in setting it up again

• I set this up on the 20th and 21st of Jan 2022. (10 PM - 4 AM)

• It all started here - http://echorand.me/site/notes/articles/sphinx/static_html.html

• Then I learnt how to embed notebooks using NBSphinx https://stackoverflow.com/questions/38526888/embed-ipython-notebook-in-sphinx-document.

• More about nbsphinx -https://nbsphinx.readthedocs.io/en/0.2.8/usage.html

• Then I learnt how to add Markdown support using https://www.sphinx-doc.org/en/master/usage/markdown.html

• I struggled a lot to understand how to use “toc”. Finally figured it out. Made structures for myself.

  • I dunno enough yet though. Maybe this will help - https://stackoverflow.com/questions/33486420/adding-files-in-subfolders-to-sphinx-documentation-sphinxcontrib-matlabdomain#51296983

• Sometimes documents don’t get displayed in the toctree. Check your indentation. https://stackoverflow.com/questions/62822605/sphinx-modules-rst-warning-document-isnt-included-in-any-toctree

• Understood the configuration - https://www.sphinx-doc.org/en/master/usage/configuration.html

• Found a bunch of themes and tried them out before zeroing in on Furo. - https://sphinx-themes.org/sample-sites/furo/

Caution

• Always add these extensions extensions = ['nbsphinx','myst_parser','IPython.sphinxext.ipython_console_highlighting']

• Always exclude these patterns exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store','**.ipynb_checkpoints']

Attention

• Always add a .nojekyll file to the production folder (build) - https://www.docslikecode.com/articles/github-pages-python-sphinx/

• Set html_title = "" if you don’t want the “documentation” string to pop up. - https://pradyunsg.me/furo/customisation/sidebar-title/

• Some random warnings : https://github.com/spatialaudio/nbsphinx/issues/24

• Some errors : https://stackoverflow.com/questions/63840334/fix-some-very-minor-issues-and-rebuild-sphinx-but-got-the-error-wrong-color-for

• Solved a few Leetcode problems just to have something to write on this site initially. Solved 4 to be precise. Good stuff.

• Moved around files from https://abhiramr.com and an older version of this site.

Misc

• Leetcode is being tracked using https://seanprashad.com/leetcode-patterns/ . Took some inspiration from Vinay’s website - https://stonecharioteer.com/ .