Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Added links to other component docs #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jun 19, 2020

Conversation

philipstarkey
Copy link
Member

@philipstarkey philipstarkey commented Jun 16, 2020

As per labscript-suite/labscript#65 this PR includes links to other subproject docs (dynamically generated to link to either stable or latest as appropriate)

rpanderson added a commit to rpanderson/labscript-suite that referenced this pull request Jun 16, 2020
rpanderson added a commit to rpanderson/labscript-suite that referenced this pull request Jun 16, 2020
rpanderson added a commit to rpanderson/labscript-suite that referenced this pull request Jun 16, 2020
@rpanderson
Copy link
Member

I've implemented my review suggestions in rpanderson/labscript-suite@bc379d6, and added a table + icons + prose to the components page in rpanderson/labscript-suite@2468dc3 which can be previewed here.

However, this is manually generated right now. We could just use a static components.rst for all (sub)projects. Also, @philipstarkey what do you think about distinguishing the metapackage docs somehow, e.g. excluding it from the toctree of components.rst and putting it as a top-level link in the sidebar of the subprojects?

* fixed typo in labscriptsuite.org URLs
* Updated to use `pathlib`
* Updated .gitignore to delineate custom and generic ignore rules
* renamed component_docs.rst -> components.rst
@philipstarkey
Copy link
Member Author

However, this is manually generated right now. We could just use a static components.rst for all (sub)projects. Also, @philipstarkey what do you think about distinguishing the metapackage docs somehow, e.g. excluding it from the toctree of components.rst and putting it as a top-level link in the sidebar of the subprojects?

If we use a static .rst file then we have to choose between linking to stable or latest. As in both stable and latest docs for (say) runmanager will link to stable for lyse. I'd rather avoid that as I think it would get confusing. You could swap from runmanager to lyse and back to runmanager through these links and end up switching from reading latest runmanager to stable runmanager. So I feel autogenerating is critical.

Given that, it's difficult to split out the metapackage link because it also needs to be autogenerated to either be latest or stable and that would require autogenerating index.rst I think.

* Now use the intersphinx mapping URL already generated
* Also added entry for metapackage
@philipstarkey
Copy link
Member Author

I have had an attempt at generating the table dynamically. Should be visible here momentarily: https://philipstarkey-labscriptsuite.readthedocs.io/en/latest/components/

I also fixed a bug with the icon width (in the table) on small screens

@philipstarkey
Copy link
Member Author

Given that, it's difficult to split out the metapackage link because it also needs to be autogenerated to either be latest or stable and that would require autogenerating index.rst I think.

I was wrong, I've found a way to split out the metapackage link while keeping the definition within the components.rst file!

philipstarkey added a commit to philipstarkey/labscript that referenced this pull request Jun 18, 2020
(hidden in docs built for this project)

* also removed metapackage table from components page (since I realised I shouldn't have really added it)
philipstarkey added a commit to philipstarkey/labscript-utils that referenced this pull request Jun 18, 2020
This is so that custom rules added by git tools will be in the right section when they are appended to the file
@rpanderson
Copy link
Member

If we use a static .rst file then we have to choose between linking to stable or latest.
...
So I feel autogenerating is critical.

By static, I meant not auto-generating the table, not the stable/latest linking. (edit: It looks like you've done that.)

I have had an attempt at generating the table dynamically. Should be visible here momentarily: https://philipstarkey-labscriptsuite.readthedocs.io/en/latest/components/

I also fixed a bug with the icon width (in the table) on small screens

Nice!

@rpanderson
Copy link
Member

rpanderson commented Jun 18, 2020

I was wrong, I've found a way to split out the metapackage link while keeping the definition within the components.rst file!

Awesome. Should we refer to it using a different term? Metapackage is kinda jargon and/or not illuminating. It's nominally 'whole suite documentation' but that's verbose. Jupyter do this using a logo link in the top right of their subprojects pages (example), but the styling/structure of their subproject documentation is inconsistent.

@philipstarkey
Copy link
Member Author

I was wrong, I've found a way to split out the metapackage link while keeping the definition within the components.rst file!

Awesome. Should we refer to it using a different term? Metapackage is kinda jargon and/or not illuminating. It's nominally 'whole suite documentation' but that's verbose. Jupyter do this using a logo link in the top right of their subprojects pages (example), but the styling/structure of their subproject documentation is inconsistent.

I've added another toctree so we can have another caption. The caption is now "FURTHER DOCUMENTATION" and the entry for the main level docs is now "The labscript suite" (removing the metapackage jargon). The next toctree ("LINKS") then follows your comment here.

@rpanderson
Copy link
Member

Neat. An alternative to "FURTHER DOCUMENTATION" would be to have a caption atop the toctree which just read "DOCUMENTATION".

@philipstarkey
Copy link
Member Author

Neat. An alternative to "FURTHER DOCUMENTATION" would be to have a caption atop the toctree which just read "DOCUMENTATION".

The main (first) toctree? Isn't that a bit redundant since it's all documentation? I was aiming to have a caption for the links to other sphinx docs that made it clear clicking on them would take you to a different sphinx site (different toctree, search, potentially version if the current docs being viewed are for a specific version and not stable/latest)

@rpanderson
Copy link
Member

rpanderson commented Jun 19, 2020

The main (first) toctree? Isn't that a bit redundant since it's all documentation?

Perhaps not entirely. Docs/docs is in the URL and RTD adornments (search bar, version bar, uppermost breadcrumb), but if we're going to use captions in the sidebar denoting links and other documentation, it mightn't hurt to use this as an additional signpost to readers that they are navigating documentation primarily (especially if they aren't familiar with RTD).

This reminds me that we might also signpost this by having the breadcrumbs all be of the form:

Docs » <project> Documentation

which is used elsewhere. At present we do so inconsistently (labscript has it; others don't).

Come to think of it, shouldn't RTD sub-projects have an additional layer of breadcrumbs, e,g,

~Docs » the *labscript suite* » lyse Documentation~

At the moment only the 'Docs' is hyperlinked, to the sub-project index. Maybe I just imagined this feature.

Update: Nevermind, I momentarily misunderstood how RTD breadcrumbs work, which is just to provide context for the toctree of a given (sub)project page.

@philipstarkey
Copy link
Member Author

Oh, if the "DOCUMENTATION" caption is in addition to the "FURTHER DOCUMENTATION" caption then I don't mind. I just want to keep the two categories separated somehow.

@rpanderson rpanderson self-requested a review June 19, 2020 06:37
@philipstarkey philipstarkey merged commit 25fe511 into labscript-suite:master Jun 19, 2020
philipstarkey added a commit to labscript-suite/labscript-utils that referenced this pull request Jun 25, 2020
commit d8b8343
Merge: 9bc7a39 bfa6932
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 20:48:39 2020 -0400

    Merge pull request #59 from philipstarkey/fix-h5py-file-mode

    Addresses #47 for this module

commit 9bc7a39
Merge: 1189334 66d0be4
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 20:30:42 2020 -0400

    Merge pull request #55 from rpanderson/example_IMAQdx_remote

    Example labscript and analysis scripts for IMAQdxCamera and RemoteBLACS

commit bfa6932
Author: philipstarkey <[email protected]>
Date:   Thu Jun 25 10:25:49 2020 +1000

    Addresses #47 for this module

commit 1189334
Merge: 5025b1b 0b0d07a
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 19:35:15 2020 -0400

    Merge pull request #54 from rpanderson/example_experiment

    Minimal working connection table and example experiment script

commit 66d0be4
Author: Russell Anderson <[email protected]>
Date:   Mon Jun 15 13:37:23 2020 +1000

    lyse analysis script demonstrating some Run methods for example_IMAQdx_remote

commit a48a9c0
Author: Russell Anderson <[email protected]>
Date:   Mon Jun 15 13:15:48 2020 +1000

    Example connection table and labscript experiment script for RemoteBLACS and IMAQdxCamera

commit 5025b1b
Merge: f77525f ed76901
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 02:16:29 2020 -0400

    Merge pull request #58 from philipstarkey/philipstarkey/issue43

    Fixes .pth file has no effect in editable install

commit ed76901
Author: chrisjbillington <[email protected]>
Date:   Wed Jun 24 01:23:44 2020 -0400

    Move copying of .pth file into setup.py

    Use a custom develop command to copy the .pth file into site-packages
    when `python setup.py develop` is run - this is what pip does under the
    hood for `pip install -e`.

    No longer need desktop-app to locate site-packages, as the setuptools
    command class knows it as `self.install_dir`.

    The file is not removed by `pip uninstall`, but due to the `try:
    except:`s in the `.pth` file, leaving it behind is harmless.

    It is removed if the user runs whatever `setup.py` command undoies

commit 894e245
Author: chrisjbillington <[email protected]>
Date:   Wed Jun 24 00:04:13 2020 -0400

    Require desktop-app 0.2.6

    Which renames `_get_install_directory` to not have an underscore,
    and which fixes a bug preventing docs from building on RTD.

commit 271439e
Author: philipstarkey <[email protected]>
Date:   Wed Jun 24 12:53:49 2020 +1000

    Removed support for custom development directories from path

commit dd098a5
Author: philipstarkey <[email protected]>
Date:   Wed Jun 24 12:38:19 2020 +1000

    Fixes .pth file has no effect in editable install
    Fixes #43

    The .pth file is now copied during `labscript-profile-create` if it does not exist in the site-packages dir (where the .egg-info files exist) and if it the .pth file exists in the package structure (aka labscript-utils it is an editable install)

    The labscript-suite.pth file has been updated to not raise an exception if labscript-suite has been uninstalled (so we do not have to worry about cleanup).

    Also updated the `labscript_profile.add_userlib_and_pythonlib` function to use the `site` library for adding userlib and pythonlib to the system path.

commit 0b0d07a
Author: Russell Anderson <[email protected]>
Date:   Mon Jun 22 17:48:00 2020 +1000

    start()/stop() in __main__ block so connection table can be imported

commit 4c19de9
Author: Russell Anderson <[email protected]>
Date:   Mon Jun 15 13:12:52 2020 +1000

    Add AnalogOut with ramp example, rename DigitalOut connection

commit 9b64a0d
Author: Russell Anderson <[email protected]>
Date:   Wed Jun 10 23:09:03 2020 +1000

    Minimal example connection table and labscript using dummy devices

commit f77525f
Author: Phil Starkey <[email protected]>
Date:   Sat Jun 20 18:09:53 2020 +1000

    Removed unnecessary fixed title from main TOC

    This was erroneously added in #57

commit 5e02b01
Merge: 3f78207 8b19766
Author: Phil Starkey <[email protected]>
Date:   Sat Jun 20 18:07:04 2020 +1000

    Merge pull request #57 from philipstarkey/master

    Changed URL for API reference to be shorter
    Fixed bug with readthedocs auto PR build

commit 8b19766
Author: philipstarkey <[email protected]>
Date:   Sat Jun 20 12:02:51 2020 +1000

    Updated method call for stylesheet to remove deprecated warning in build

commit 56fdd63
Author: philipstarkey <[email protected]>
Date:   Sat Jun 20 11:46:33 2020 +1000

    Fixed sphinx conf to detect PR builds and link to 'latest' instead of stable

commit 9889d19
Author: philipstarkey <[email protected]>
Date:   Sat Jun 20 10:44:04 2020 +1000

    Changed URL for API reference to be shorter

commit 3f78207
Merge: bbd928a bf9d10e
Author: Phil Starkey <[email protected]>
Date:   Fri Jun 19 18:58:37 2020 +1000

    Merge pull request #56 from philipstarkey/master

    Added links to other component docs

commit bf9d10e
Author: philipstarkey <[email protected]>
Date:   Fri Jun 19 16:06:09 2020 +1000

    Addressing latest review comments

commit e75b6bc
Author: philipstarkey <[email protected]>
Date:   Fri Jun 19 11:23:49 2020 +1000

    Updated docs to use jinja template for component doc links

commit 9c61238
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 17:14:57 2020 +1000

    Removed autogenerated rst file from version control

commit 2303185
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:43:29 2020 +1000

    Updated .gitignore with latest GitHub defaults

commit 87b757e
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:39:52 2020 +1000

    Relocated custom sphinx gitignore rules

commit 75813a5
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:31:01 2020 +1000

    Updated PR as per review in labscript-suite/labscript-suite#48

commit bbd928a
Author: Russell Anderson <[email protected]>
Date:   Wed Jun 17 11:39:17 2020 +1000

    Populated README.md with styling, iconogrpahy, prose, and badges

commit 573c521
Author: philipstarkey <[email protected]>
Date:   Tue Jun 16 18:10:25 2020 +1000

    Added links to other component docs
philipstarkey added a commit to labscript-suite/labscript that referenced this pull request Jun 25, 2020
commit c3b7988
Author: Phil Starkey <[email protected]>
Date:   Thu Jun 25 18:27:06 2020 +1000

    Update labscript_utils dependency to `>=3.0.0`

commit 822e5d5
Merge: 2e2785c 39c6f0b
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 15:48:15 2020 +1000

    Merge pull request #69 from rpanderson/example_fix

    Make example labscript functional and format using black

commit 39c6f0b
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 12:34:08 2020 +1000

    Name all the args

commit 255d74e
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 12:11:48 2020 +1000

    Name all arguments in connection table

commit e3d3ece
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 11:08:25 2020 +1000

    Omit __init__ import and comply with flake8 F403

commit 6b26f1f
Author: Russell Anderson <[email protected]>
Date:   Sun May 31 17:38:18 2020 +1000

    Make example labscript functional and format using black

commit 2e2785c
Merge: 62b9098 4e77810
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 21:22:05 2020 -0400

    Merge pull request #70 from rpanderson/is-syntax-warning-bugfix

    Bugfix for ValueError introduced in #68

commit 4e77810
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 11:18:56 2020 +1000

    Abbreviated bugfix.

commit a667f7e
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 11:17:11 2020 +1000

    Bugfix for ValueError introduced in #68

commit 62b9098
Merge: 0e23ed0 1746399
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 20:49:32 2020 -0400

    Merge pull request #67 from philipstarkey/fix-h5py-file-mode

    Fix h5py deprecation warning

commit 0e23ed0
Merge: 5b52c20 6373f02
Author: Chris Billington <[email protected]>
Date:   Wed Jun 24 18:47:18 2020 -0400

    Merge pull request #68 from rpanderson/is-syntax-warning

    Do not use 'is' for numeric literal comparisons

commit 6373f02
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 08:36:55 2020 +1000

    Omitted 'is' with numeric literal comparisons

commit 1746399
Author: philipstarkey <[email protected]>
Date:   Wed Jun 24 18:29:12 2020 +1000

    Fix h5py deprecation warning

    Addresses labscript-suite/labscript-utils#47 for the labscript module

commit 5b52c20
Merge: 0362fa7 88ce952
Author: Russell Anderson <[email protected]>
Date:   Mon Jun 22 18:09:54 2020 +1000

    Merge pull request #66 from philipstarkey/master

    Doc updates

commit 88ce952
Author: philipstarkey <[email protected]>
Date:   Sat Jun 20 18:17:23 2020 +1000

    Doc updates

    Renamed API reference URL to match labscript utils and updated config to fix bugs identified in labscript-suite/labscript-utils#57

commit 0362fa7
Merge: 74869ef 52d3b9f
Author: Phil Starkey <[email protected]>
Date:   Fri Jun 19 18:58:04 2020 +1000

    Merge pull request #65 from philipstarkey/master

    Updated docs to follow our standard conf

commit 52d3b9f
Author: philipstarkey <[email protected]>
Date:   Fri Jun 19 16:04:04 2020 +1000

    Addressing latest review comments

commit 7674a8f
Author: philipstarkey <[email protected]>
Date:   Fri Jun 19 11:19:33 2020 +1000

    Updated docs to use jinja template for component doc links

commit d4474e2
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:43:10 2020 +1000

    Updated .gitignore with latest GitHub defaults

commit a18a0d1
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:39:35 2020 +1000

    Relocated custom sphinx git ignore rules

commit 80aa5a1
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:21:44 2020 +1000

    Restored 64 pixel logo accidentally replaced with 32 pixel logo

commit 42d3bc6
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:17:42 2020 +1000

    Updated install requirement to 3.0.0rc1+

commit 1961a2c
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:13:40 2020 +1000

    testing dependency fix

commit 234753d
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:07:41 2020 +1000

    Updated as per the review in labscript-suite/labscript-suite#48

commit 74869ef
Author: Russell Anderson <[email protected]>
Date:   Wed Jun 17 10:24:43 2020 +1000

    Populated README.md with styling, iconogrpahy, prose, and badges

commit 28dc675
Author: philipstarkey <[email protected]>
Date:   Tue Jun 16 18:24:26 2020 +1000

    Removed unnecessary header and added intersphinx link

commit 35c5466
Author: philipstarkey <[email protected]>
Date:   Tue Jun 16 17:19:33 2020 +1000

    Updated docs to follow our standard conf

    Also added links to other labscript suite docs and standard links.

Co-authored-by: chrisjbillington <[email protected]>
Co-authored-by: Russell Anderson <[email protected]>
philipstarkey added a commit that referenced this pull request Jun 25, 2020
commit 76e7b63
Author: Phil Starkey <[email protected]>
Date:   Thu Jun 25 20:09:18 2020 +1000

    Update dependencies in setup.cfg

    Bumped all labscript-suite dependencies to `>=3.0.0`

commit 1567faa
Merge: 17f02fe e0ac239
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 15:48:24 2020 +1000

    Merge pull request #50 from rpanderson/labscript-profile-dir-docs

    Clarify note about labscript-suite/labscript-utils#37

commit e0ac239
Author: Russell Anderson <[email protected]>
Date:   Thu Jun 25 15:43:26 2020 +1000

    Clarify note about labscript-suite/labscript-utils#37

commit 17f02fe
Merge: 907619d 90330ba
Author: Russell Anderson <[email protected]>
Date:   Mon Jun 22 18:08:23 2020 +1000

    Merge pull request #49 from philipstarkey/master

    fix docs conf bugs identified in labscript-suite/labscript-utils#57

commit 90330ba
Author: philipstarkey <[email protected]>
Date:   Sat Jun 20 18:14:39 2020 +1000

    fix docs conf bugs identified in labscript-suite/labscript-utils#57

commit 907619d
Author: Russell Anderson <[email protected]>
Date:   Fri Jun 19 16:50:41 2020 +1000

    64x64 icons per other styling, and https doi badge

commit 25fe511
Merge: fadeab2 3b8377d
Author: Phil Starkey <[email protected]>
Date:   Fri Jun 19 16:43:34 2020 +1000

    Merge pull request #48 from philipstarkey/master

    Added links to other component docs

commit 3b8377d
Author: philipstarkey <[email protected]>
Date:   Fri Jun 19 15:57:44 2020 +1000

    Addressing latest review comments

commit d5e175b
Author: philipstarkey <[email protected]>
Date:   Fri Jun 19 10:56:52 2020 +1000

    Simplified sphinx conf by moving logic into template

commit 6abe116
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 19:14:25 2020 +1000

    Moved auto generated components.rst to a jinja2 template

commit 8159129
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:43:21 2020 +1000

    Updated .gitignore with latest GitHub defaults

commit d697cb9
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:40:30 2020 +1000

    Relocated custom sphinx gitignore rules (and restored the original)

commit 42172f5
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:32:45 2020 +1000

    reversed order of sections in .gitignore

    This is so that custom rules added by git tools will be in the right section when they are appended to the file

commit cb399ec
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 16:09:49 2020 +1000

    Split out metapackage link in generalised config
    (hidden in docs built for this project)

    * also removed metapackage table from components page (since I realised I shouldn't have really added it)

commit a00526b
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 13:06:16 2020 +1000

    Fixed bug where component docs URLs were alsways using "latest".

    * Now use the intersphinx mapping URL already generated
    * Also added entry for metapackage

commit 58ed4fd
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 12:31:24 2020 +1000

    Added dynamic generation of labscript suite component table

commit b3087a6
Author: philipstarkey <[email protected]>
Date:   Thu Jun 18 11:10:54 2020 +1000

    Implemented some review changes

    * fixed typo in labscriptsuite.org URLs
    * Updated to use `pathlib`
    * Updated .gitignore to delineate custom and generic ignore rules
    * renamed component_docs.rst -> components.rst

commit fadeab2
Author: Russell Anderson <[email protected]>
Date:   Wed Jun 17 11:38:48 2020 +1000

    README.md badges and edits

commit e419ce1
Author: Russell Anderson <[email protected]>
Date:   Tue Jun 16 21:03:32 2020 +1000

    Populated README.md with styling, iconogrpahy, prose, and badges

commit 8e5ea93
Author: philipstarkey <[email protected]>
Date:   Tue Jun 16 18:08:33 2020 +1000

    black formatting

commit 0f0da2e
Author: philipstarkey <[email protected]>
Date:   Tue Jun 16 18:06:02 2020 +1000

    Added links to other component docs

Co-authored-by: Russell Anderson <[email protected]>
This was referenced Jun 25, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants