search

NSLS-II / docs

Standards Documentation for NSLS-II DAQ and Analysis
https://nsls-ii.github.io
BSD 2-Clause "Simplified" License
2 stars 13 forks source link

connect between different parts of the documentation #73

Open prjemian opened 6 years ago

prjemian commented 6 years ago

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.

mrakitin commented 6 years ago

Great idea, I also always miss those higher level menu items.

mrakitin commented 6 years ago

Here is the toctree for general docs:

.. toctree::
   :hidden:
   :maxdepth: 2

   architecture-overview
   cookbook/index
   tutorials
   remote-access
   sandbox
   history
   conda
   fresh-installation
   resources
   internal_index

.. toctree::
   :hidden:
   :caption: Data Collection

   bluesky <https://nsls-ii.github.io/bluesky>
   ophyd <https://nsls-ii.github.io/ophyd>

.. toctree::
   :hidden:
   :caption: Data Access and Management

   databroker <https://nsls-ii.github.io/databroker>
   amostra <https://nsls-ii.github.io/amostra>
   datamuxer <https://nsls-ii.github.io/datamuxer>
   suitcase <https://nsls-ii.github.io/suitcase>

.. toctree::
   :hidden:
   :caption: Data Analysis

   scikit-beam <http://scikit-beam.github.io/scikit-beam>

.. toctree::
   :hidden:
   :caption: GitHub Links

   NSLS-II Repositories <https://github.com/NSLS-II/>
   Wish List <https://github.com/NSLS-II/wishlist/issues>
   Bug Reports <https://github.com/NSLS-II/Bug-Reports/issues>

and Bluesky's ones:

.. toctree::
   :caption: User Documentation
   :maxdepth: 1

   plans_intro
   documents
   metadata
   plans
   callbacks
   state-machine
   simulation
   progress-bar
   event_descriptors
   async
   debugging
   run_engine_api
   magics
   comparison-with-spec

.. toctree::
   :caption: Developer Documentation
   :maxdepth: 1

   hardware
   msg
   run_engine
   api_changes

Probably we should always have the block with the external links. @danielballan, @tacaswell, any objections? I can go ahead and take care of doc change for all the packages.

mrakitin commented 6 years ago

Sorry, placed the snippets to wrong places. Corrected in my previous comment.

danielballan commented 6 years ago

Yep, that would be great. We can also make more use of the intersphinx plugin, but that's a separate issue.

mrakitin commented 6 years ago

Cool, will take care of it.

prjemian commented 6 years ago

Wow, Thanks!

mrakitin commented 6 years ago

6 PRs are awaiting review... Did I miss anything? Scikit-beam seems to have different documentation style and does not contain any links to other documentation projects.

mrakitin commented 6 years ago

I removed scikit-beam and wish list repos from project-specific docs for all 6 projects.