nsls-ii/docs

Standards Documentation for NSLS-II DAQ and Analysis

multi-project docs

Documentation for NSLS-II DAQ and Analysis

Developer Documentation

This repo and others build the sphinx on Travis-CI and force-push the build products to the repo NSLS-II/NSLS-II.github.io.

If you haven't done this before:

gem install travis
travis login

Then:

ssh-keygen -t rsa -C "bluesky-docs-deploy"
travis encrypt-file bluesky-docs-deploy --repo NSLS-II/bluesky
git add bluesky-docs-deploy.enc

Copy the openssl ... line output from the travis... command above and use it in the .travis.yml.

Add the public key, bluesky-docs-deploy.pub, as a "Deploy Key" in the settings of the NSLS-II.github.io repository.

docs's Issues

Move/remove the old tutorial material in this repo

Instead link to the bluesky, databroker, and (forthcoming) ophyd tutorials.

need docs for configure_base and configure_olog

@danielballan
for this code:
https://github.com/NSLS-II/nslsii/blob/master/nslsii/__init__.py

add documentation to:
https://github.com/NSLS-II/docs/blob/master/source/fresh-installation.rst

example:

import nslsii
nslsii.configure_base(get_ipython().user_ns, 'iss', pbar=False, bec=False)

docs broken, couldn't connect to db

inline ipython dumped traceback cuz it can't connect to the db

https://nsls-ii.github.io/broker/basics.html
/filestore/index.html
/examples/show-and-plot-scalar-data.html
/examples/advanced-live-plot.html

Off-topic: XPD needs retricted bash removed

Creating an issue so we don't forget to make sure this gets done.

should add 4 package level hierarchy to docs

4 levels of device definition / instantiation

1. opyhd :: cross facility package, class definition only
2. nslsii_tools :: nsls-ii specific classes and plans. Factory
   functions to make standard objects (ring
   current, etc)
3. BEAMLINETOOLS :: beamline specific classes, plans, factory
   functions, maybe direct instatiation of devices
4. beamline plofile :: maybe class definition (should move up),
   device connection / instatiation

I suggest a new section: NSLS-II packaging practices (or hierarchy)
@tacaswell ?

Update links in sidebar

I suggest adding caproto (requested by Dan Flath, who looked for it there and was surprised not to find it) and removing amostra and datamuxer at least for now, as presently dormant and poorly documented. Objections?

Document the `Data` class in ophyd

Add examples for using the peak stats estimations in ophyd/userapi/scan_api.py

/DATA, /POOL, broker dns aliases

Was doing some fs work on 5id and had this doc pointed out to me.
https://github.com/NSLS-II/docs/blob/master/deploying/metadatastore.rst

• There is not yet a consistent standard (we're working on it) for filesystem naming :( /DATA and /POOL are not ubiquitous.
• We don't have any write-once filesystems; there's no need for data and analysis to be on different filesystems.
• The "broker" dns alias just adds complexity. It's much easier to edit/manage/debug the conf files for mds and fs than to make dns changes

Metadatastore documents

Did we decide that every document type in metadatastore has a time field?

build package version dashboard

Prior art:
https://pyviz.org/tools.html
https://github.com/pyviz/website
https://github.com/NSLS-II/cantrips/blob/master/cookbooks/gh_tag_listing.org

Use tagged versions of tomopy and dxchange for the tomopy reconstruction example

A new version of tomopy can be installed with pip install .. See #97 which uses this new approach and installs tomopy from the master branch. Once the new version of tomopy is tagged/released (most likely https://github.com/tomopy/tomopy/releases/tag/1.2.2), we should use the tagged version and install it with:

pip install git+https://github.com/tomopy/[email protected]

Currently, we install the dxchange package from the master branch of their repo:

docs/requirements.txt

Line 25 in c1bd534

git+https://github.com/data-exchange/dxchange

Once the installer of dxchange is updated (see my issue data-exchange/dxchange#81), we will be able to install it with:

pip install git+https://github.com/data-exchange/[email protected]

Revert to using standard doctr

Once @danielballan PR into doctr is resolved (drdoctr/doctr#190) and the version of doctr is release. Then we should stop installing Dan's version and go back to the standard doctr.

Set up 'uptime robot' or similar

We should set up Uptime Robot to notify [email protected] when any of our public sites fall over. Prompted by scikit-beam/scikit-beam#543

Restructure this repo as NSLS-II specific

The general bluesky project content will move to bluesky.github.io (aliased as blueskyproject.io). This repository will focus on local deployment documentation and resources.

Turn SRX use cases into examples.

See https://github.com/NSLS-II-SRX/nsls2-xf-utils

Update pyOlog instructions

Direct people to https://logbook.nsls2.bnl.gov

Sandbox Security Certificate expired

The security certificate has expired for the Sandbox. See attached screen:

times are my local (CDT), I believe.

connect between different parts of the documentation

Navigating amongst the different components could be easier if there were cross-references between components.

For example: bluesky should point to (at least) NSLS-II Software Documentation

This would be most accessible somewhere in the left sidebar.

Rather than decide which things to put in the sidebar, put the same block of all components in the sidebar of every component. This will help document and unify the entire suite of software.

Migrate "how to create a new conda channel" to deployment docs

from https://3.basecamp.com/3733838/buckets/4534819/messages/1344262490

suggest IP for host?

One issue. For adding a jupyter kernel, I had to change from using the hostname string to a specific IP address. I'm not sure where along the chain the issue is.

However, this could be an issue that others encounter. I'd suggest adding to these docs
https://nsls-ii.github.io/conda.html#access-custom-user-environments-in-nsls-ii-s-jupyterhub

something like:
tip : if you are having kernel connection problems, try replacing the hostname with an actual ip address. You may find your ip address by typing ip addr on the host machine.

@danielballan do you agree? i will PR if yes. This issue is also meant to flag this general problem

Remove the "Fresh installation" stuff which is out of date

h/t @mrakitin