#################################
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 <https://robinboncoeur.github.io/KeysToLife/index.html>`_ as my test app. `KeysToLife <https://robinboncoeur.github.io/KeysToLife/index.html>`_ 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 <https://desktop.github.com/>`_ 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!