A Bit of Git, mostly Sphinx Notes

Stuff on here sort-of works, sort-of. I wrote this in Nov 2018. I’ll do some testing of this process as I’ve already encountered issues I couldn’t explain when I cerated this set of documents called HelpYrself. If it works for you, great. However, YMMV.

Update 18.11.17: Using KeysToLife as my test app. KeysToLife is a collection of emailed devotionals that are worth reading more than just once, so I’m saving them in this document.

01 - Github Setup

On my Mac, in the main user folder - sort-of like the “Home/Username” folder in Linux - there is an AllHelp folder containing subfolders for each product, as well as a folder in AllHelp/GitPages, where all build files end up. If a new product’s users would benefit from some sort of help system for that product, the product get a folder in that AllHelp folder. Any product with users will have a repository for that product on GitHub.

Using as an example a document called “KeysToLife”, the following approach more-or-less seems to get the job done. You will need two instances of Terminal running: one for Sphinx to build html from .rst files, the other, to talk to github.

I now use Github Desktop which makes the process infinitely simpler, particularly when I stuff things up: it suggests solutions, which the commandline approach doesn’t do.

02 - Sphinx

Note: this Sphinx section updated, with the following notes, on 2022.06.05

Sphinx Install

Tried installing Sphinx via Homebrew. make html wouldn’t work, so I uninstalled and tried:

python3 -m pip install sphinx

make html still wouldn’t work, so figured it was a path issue. Located sphinx-build:

which sphinx-build

Added the current python3 path to .profile:

export PATH="/Users/robyn/Library/Python/3.8/bin/:$PATH"

Now, make html works. Additionally added my main theme:

pip3 install -U sphinx-rtd-theme

New Sphinx Document Set

In the first terminal, run:

cd AllHelp/NewDocsSet

sphinx-quickstart

In the list of prompts, it will ask whether to separate source from build: I have selected No. Note:

where this approach suggested, the author said to choose Yes. It sort-of didn’t work quite as I had anticipated, so I’m selecting No.

In order to have the build end up in the right place, I have the following entry in the Makefile:

BUILDDIR      = /Users/robyn/AllHelp/GitPages/KeysToLife/docs/

Also, change the following:

    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

...to...

@$(SPHINXBUILD) -b help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

This allows the github-pages to find the source for the pages in the /main/docs/ folder in your repository.

index.rst

In the newly created index.rst, change the title of the header as desired, then add the pages in the RSTs folder so that index.rst refllects what’s in the RSTs folder:

.. toctree::
   :maxdepth: 3
   :caption: Contents:


   RSTs/Introduction.rst
   RSTs/Des.rst
   RSTs/Eli.rst
   RSTs/Spurg.rst

Modify the conf.py for sphinx to use the ReadTheDocs template, which I find easily more useful than some of the others:

html_theme = 'sphinx_rtd_theme'

html_theme_options = {
    'canonical_url': '',
    'analytics_id': '',
    'logo_only': False,
    'display_version': True,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,
    #'vcs_pageview_mode': '',
    # Toc options
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False
}

Make sure to remove an indenting copying and pasting this last configuration text might introduce, as python sees indenting as a means of marking blocks of code. After adding your files to the RSTs folder and editing them, include them in your index.rst.

Newest sphinx-build version (5.0) requires a language:

language = 'en-English'

Note: previous CLI approach to github and git now done in Github Desktop. Just to much easier!