Content

  • This example uses package name mypackage, which should be replaced by the real package name.
  • It seems like names html, gh-pages are static.

Create local release

As usually, nothing special:

cd <some-directory>
source /reg/g/psdm/bin/conda_setup
condarel --newrel --name con-doc # name is arbitrary
cd con-doc
source conda_setup

Add package/repository from github

Being on pslogin (now it also works on psana nodes):

git clone https://github.com/lcls-psana/mypackage.git
# or
condarel --addpkg --name mypackage --tag HEAD

Set up sphinx within main repository

Add Sphinx configuration files in the directory web. The name web is arbitrary but for the purpose of further automation it would be nice to respect it as static.

mkdir mypackage/doc/web
cd mypackage/doc/web
sphinx-quickstart
Then in dialog with sphinx-quickstart type-in non-default answers for options as follows.
> Project name: mypackage-doc
> Author name(s): Your Name and Titles Here
> Project version []: 1.1
> Project release [1.1]: 1
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y

In principle now documentation can be generated. But we do not want to mix it with code and will add it to the separate branch with static name gh-pages doing tricks as follows.

Set up separate directory and repository for documentation

mkdir ../../../mypackage-doc # arbitrary, but the same path should be in the Makefile...
cd ../../../mypackage-doc
git clone https://github.com/lcls-psana/mypackage.git html
cd html

Create new branch, set link, clean-up

git branch gh-pages # this is a static name recognized by github...
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx # -A-A-A !!! this command deletes everything ... from the branch gh-pages, not master
git branch # just check that you are in * gh-pages

Change configuration files

Makefile

Need to change BUILDDIR in order to not spoil master branch

cd ../../mypackage/doc/web/
emacs Makefile
--------------
# BUILDDIR      = build
BUILDDIR      = ../../../mypackage-doc

index.rst

Add something like

:maxdepth: 3

.. automodule:: <your module name>
   :members:
   :show-inheritance:
   :special-members:
   :private-members:
.. autosummary::
   :toctree: _autosummary

conf.py

At least need to set path to the source files which docstrings are going to be used:

import os
import sys
sys.path.insert(0, os.path.abspath('../../src')) # ABSOLUTE PATH!!!

# for my personal preferences:
'sphinx.ext.autosummary'
autosummary_generate = True
# html_theme = 'alabaster'
html_theme = 'agogo'

#        'about.html',
#        'donate.html',

#add:
def setup(app):
    app.add_stylesheet('my_theme.css')

Add _static/my_theme.css containing

.wy-nav-content {
    max-width: 900px !important;
}

Commit changes to master

git add -A
dir status
git commit -m "add sphinx doc"
git push origin master

Generate documentation

assuming that we are in .../con-doc/mypackage/doc/web

cd .../mypackage
scons # I am not sure, but it probably needs to be done for cross-references...

cd doc/web
make html

Commit changes to gh-pages

cd ../../../mypackage-doc/html
git branch # make sure that it is * gh-pages
git status
git add -A
git commit -m "add/update doc"
git push origin gh-pages

Shortcut for commands above.

Setup package structure to generate documentation

  • TBD - need in script which creates sphinx configuration files (equivalent to sphinx-quickstart) but with significantly extended Makefile.

  • For now copy psalgos/doc/web directory to mypackage/doc/web and edit Makefile, fonf.py and index.rst files.

Generate documentation

After staging or committing code changes

cd doc/web
make newdoc

 

Change GitHub Pages settings

This step needs to done if mypackage already has associated Wiki pages. By default the link to documentation https://lcls-psana.github.io/mypackage/ points to master repo documentation. This needs to be changed to gh-pages in Setting for mypackage repo.

On https://github.com/lcls-psana/mypackage.git click Settings, scroll down to section GitHub Pages, and set correct Source pointing to gh-pages branch, then save settings.

See documentation

https://lcls-psana.github.io/mypackage/

For example:

 

References

 

 

  • No labels