Versions Compared

Old Version 1

changes.mady.by.user Mikhail Dubrovin

Saved on

compared with

New Version Current

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 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
...
Change configuration files
Makefile
...
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
 Code Block
: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:
...
 Code Block
.wy-nav-content {
    max-width: 900px !important;
}
Commit changes to master
 Code Block
git add -A
dir status
git commit -m "add sphinx doc"
git push origin master
...
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
 
See documentation
https://lcls-psana.github.io/psalgos/
References
Create local release
 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
 Code Block
git clone https://github.com/lcls-psana/psalgos.git
# or
condarel --addpkg --name psalgos --tag HEAD
 
Set up sphinx within main repository
 Code Block
mkdir psalgos/doc/web
cd psalgos/doc/web
sphinx-quickstart
Then in dialog with sphinx-quickstart type-in non-default answers for options as follows.
 Code Block
> Project name: psalgos-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,  doing tricks as follows.
Set up separate directory and repository for documentation
...
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
 Code Block
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:
  • https://lcls-psana.github.io/psalgos/
  • https://lcls-psana.github.io/PSCalib/psalgos.git html
cd html
    Create new branch, set link, clean-up
     Code Block
    git branch gh-pages
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx # A-A-A-A !!! this command removes everything ... from the branch gh-pages, not master
git branch # just check that you are in * gh-pages
     
    Makefile changes
    Need to change BUILDDIR in order to not spoil master branch
     Code Block
    cd ../../psalgos/doc/web/
emacs Makefile
--------------
# BUILDDIR      = build
BUILDDIR      = ../../../psalgos-doc
     
    index.rst changes
    Add something like
     Code Block
    :maxdepth: 3

.. automodule:: <your module name>
   :members:
   :show-inheritance:
   :special-members:
   :private-members:
.. autosummary::
   :toctree: _autosummary
     
    conf.py changes
    At least need to set path to the source files which docstrings are going to be used:
     Code Block
    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
     Code Block
    .wy-nav-content {
    max-width: 900px !important;
}
    Commit changes
     Code Block
    git add -A
dir status
git commit -m "add sphinx doc"
git push origin master
    Generate documentation
    assuming that we are in .../con-doc/psalgos/doc/web
     Code Block
    cd .../psalgos
scons

cd doc/web
make html
    Commit changes of documentation branch
     Code Block
    cd ../../../psalgos-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
     
    See documentation
  • https://lcls-psana.github.io/psalgosDetector/
 
References