Versions Compared

Old Version 2

changes.mady.by.user Mikhail Dubrovin

Saved on

compared with

New Version 3

changes.mady.by.user Mikhail Dubrovin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content

Table of Contents

Note
  • This example uses package name
psalgos
  • 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:

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

Add package/repository from github

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

Code Block
git clone https://github.com/lcls-psana/psalgosmypackage.git
# or
condarel --addpkg --name psalgosmypackage --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.

Code Block
mkdir psalgosmypackage/doc/web
cd psalgosmypackage/doc/web
sphinx-quickstart

...

Code Block
> Project name: psalgosmypackage-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

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

Create new branch, set link, clean-up

Code Block
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-A !!! this command removesdeletes everything ... from the branch gh-pages, not master
git branch # just check that you are in * gh-pages

...

Need to change BUILDDIR in order to not spoil master branch

Code Block
cd ../../psalgosmypackage/doc/web/
emacs Makefile
--------------
# BUILDDIR      = build
BUILDDIR      = ../../../psalgosmypackage-doc

index.rst

Add something like

...

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

Code Block
cd .../psalgos
sconsmypackage
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

Code Block
cd ../../../psalgosmypackage-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

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/psalgosmypackage/ points to master repo documentation. This needs to be changed to gh-pages in Setting for psalgos mypackage repo.

On https://github.com/lcls-psana/psalgosmypackage.git click Settings and , 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

...