-
Notifications
You must be signed in to change notification settings - Fork 38
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
Conversation
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 |
* 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
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
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 |
I was wrong, I've found a way to split out the metapackage link while keeping the definition within the components.rst file! |
(hidden in docs built for this project) * also removed metapackage table from components page (since I realised I shouldn't have really added it)
This is so that custom rules added by git tools will be in the right section when they are appended to the file
By static, I meant not auto-generating the table, not the stable/latest linking. (edit: It looks like you've done that.)
Nice! |
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. |
Neat. An alternative to "FURTHER DOCUMENTATION" would be to have a caption atop the |
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) |
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:
which is used elsewhere. At present we do so inconsistently (labscript has it; others don't).
Update: Nevermind, I momentarily misunderstood how RTD breadcrumbs work, which is just to provide context for the toctree of a given (sub)project page. |
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. |
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
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]>
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]>
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)