Update installation docs 1.4.1 #1810
Conversation
WalkthroughThis update primarily focuses on changing package management commands from Changes
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (5)
- .conda/README.md (2 hunks)
- .github/workflows/website.yml (2 hunks)
- docs/_static/css/tabs.css (1 hunks)
- docs/conf.py (3 hunks)
- docs/installation.md (6 hunks)
Files skipped from review due to trivial changes (2)
- .conda/README.md
- docs/_static/css/tabs.css
Additional context used
Ruff
docs/conf.py
1-1: UTF-8 encoding declaration is unnecessary (UP009)
Remove unnecessary coding comment
LanguageTool
docs/installation.md
[grammar] ~3-~3: The operating system from Apple is written “macOS” (MAC_OS)
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...
[grammar] ~3-~3: The word ‘install’ is not a noun. (A_INSTALL)
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...
[style] ~334-~334: As a shorter alternative for ‘able to’, consider using “can”. (BE_ABLE_TO)
Context: ...nning the diagnostics to see what SLEAP is able to detect on your system: ```bash sleap-d...
[style] ~340-~340: Consider using “unable” to avoid wordiness. (NOT_ABLE_PREMIUM)
Context: ...`bash sleap-diagnostic ``` If you were not able to get SLEAP installed, activate the co...
Markdownlint
docs/installation.md
64-64: Expected: 1; Actual: 0; Above (MD022, blanks-around-headings)
Headings should be surrounded by blank lines
219-219: Expected: fenced; Actual: indented (MD046, code-block-style)
Code block style
238-238: Expected: fenced; Actual: indented (MD046, code-block-style)
Code block style
257-257: Expected: fenced; Actual: indented (MD046, code-block-style)
Code block style
Additional comments not posted (10)
.github/workflows/website.yml (2)
11-11: Update to workflow triggersThe addition of the branch
liezl/update-intallation-docs-1.4.1to the trigger list ensures that any changes pushed to this branch will initiate the build process for the website. This is important for testing changes in a live environment before merging them into the main development or production branches.
45-45: Addition ofsphinx-tabspackage installationInstalling the
sphinx-tabspackage as part of the documentation build process is a good practice. This ensures that the necessary dependencies for rendering tabbed content in the documentation are met, aligning with the changes in documentation structure to include tabs.docs/conf.py (3)
62-62: Addition ofsphinx_tabs.tabsextensionThe inclusion of the
sphinx_tabs.tabsextension is essential for supporting tabbed content in the documentation. This aligns with the PR's objective to introduce tabs in the installation guide, enhancing the organization and readability of the documentation.
177-182: Configuration of CSS for tabsSpecifying
css/tabs.cssin thehtml_css_filesensures that the custom styles for the tabbed interfaces are correctly applied to the HTML output. This customization is important for maintaining a consistent and professional appearance in the documentation.
230-232: Disabling default CSS loading forsphinx_tabsSetting
sphinx_tabs_disable_css_loadingtoTrueis a thoughtful decision to avoid conflicts and redundancy in CSS loading. This ensures that only the theme's CSS is used, which can help in maintaining a cleaner and more streamlined styling in the documentation.
[APROVED]docs/installation.md (5)
3-3: Grammar correction for 'Mac OS'Consider changing "Mac OS" to "macOS" to adhere to Apple's branding guidelines. This is a minor but important detail for maintaining professionalism in documentation.
- SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. + SLEAP can be installed as a Python package on Windows, Linux, and macOS.Tools
LanguageTool
[grammar] ~3-~3: The operating system from Apple is written “macOS” (MAC_OS)
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...
[grammar] ~3-~3: The word ‘install’ is not a noun. (A_INSTALL)
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...
5-16: Introduction of tabbed interface for installation commandsThe use of tabs to separate installation commands for different operating systems is a great way to organize content, making it easier for users to find the information that's relevant to them. This aligns with the PR's objectives to improve the clarity and usability of the installation instructions.
26-42: Enhanced user guidance for terminal usageProviding detailed instructions on how to open a terminal on different systems enhances user accessibility and support, especially for those who may be less familiar with these operations. The inclusion of personal preferences and alternatives like Cmder and Windows Terminal is a nice touch that offers additional value to the user.
Line range hint
46-58: Recommendation for package manager usageThe strong recommendation to use Miniconda and guidance on managing multiple conda-based package managers are crucial for preventing installation conflicts and ensuring a smooth setup process. This advice is particularly valuable given the complex dependencies of SLEAP.
Tools
LanguageTool
[grammar] ~3-~3: The operating system from Apple is written “macOS” (MAC_OS)
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...
[grammar] ~3-~3: The word ‘install’ is not a noun. (A_INSTALL)
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...
63-182: Comprehensive installation methods and precautionsThe detailed explanation of different installation methods, along with specific commands and conditions for each scenario, provides a thorough guide for users. This section effectively addresses various user needs and scenarios, ensuring that users have all the information they need to successfully install SLEAP.
Tools
Markdownlint
64-64: Expected: 1; Actual: 0; Above (MD022, blanks-around-headings)
Headings should be surrounded by blank lines
There was a problem hiding this comment.
Actionable comments posted: 0
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (2)
- docs/conf.py (3 hunks)
- docs/installation.md (6 hunks)
Additional context used
LanguageTool
docs/installation.md
[grammar] ~3-~3: The operating system from Apple is written “macOS”
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...(MAC_OS)
[grammar] ~3-~3: The word ‘install’ is not a noun.
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...(A_INSTALL)
[uncategorized] ~187-~187: “you” seems less likely than “you’re” (you are).
Context: ... ## Testing that things are working If you installed usingconda, first activate...(AI_HYDRA_LEO_CP_YOU_YOUARE)
[uncategorized] ~229-~229: “you” seems less likely than “you’re” (you are).
Context: ....0.19041-SP0 ### GPU support Assuming you installed using either of theconda-b...(AI_HYDRA_LEO_CP_YOU_YOUARE)
[style] ~341-~341: Consider using “unable” to avoid wordiness.
Context: ...`bash sleap-diagnostic ``` If you were not able to get SLEAP installed, activate the co...(NOT_ABLE_PREMIUM)
Additional comments not posted (4)
docs/conf.py (2)
62-62: Approved: Addition ofsphinx_tabs.tabsextension.The addition of the
sphinx_tabs.tabsextension is correctly implemented and aligns with the PR objectives to enhance documentation modularity.
178-182: Approved: Custom CSS configuration and disabling default CSS loading.The configuration for the custom CSS file (
css/tabs.css) is correctly specified, and disabling the default CSS loading (sphinx_tabs_disable_css_loading = True) allows for greater customization. These settings enhance the visual consistency of the documentation and align with the PR objectives.Also applies to: 233-233
docs/installation.md (2)
5-16: Approved: Use of tabs for installation instructions.The use of tabs to organize installation instructions for different operating systems and methods significantly improves readability and accessibility. This change aligns with the PR objectives to enhance the documentation's structure and usability.
Also applies to: 68-90
8-9: Approved: Replacement ofmambacommands withconda.The replacement of
mambacommands withcondathroughout the installation instructions is correctly implemented and aligns with the PR objectives. This change simplifies the installation process and ensures consistency in the use of package managers, reducing potential confusion for users.Also applies to: 13-14, 74-75, 84-85, 110-110, 115-115, 149-149, 154-154, 167-167
not switching when change dark/light themes
with dark/light toggle button
There was a problem hiding this comment.
Actionable comments posted: 2
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (3)
- .github/workflows/website.yml (3 hunks)
- dev_requirements.txt (1 hunks)
- docs/_static/css/tabs.css (1 hunks)
Additional comments not posted (5)
dev_requirements.txt (3)
8-8: Approved version constraint for Sphinx.The updated version constraint for
sphinxensures compatibility with thesphinxcontrib.applehelpextension, aligning with the project's requirements.
12-12: Approved addition ofsphinx-tabs.The addition of
sphinx-tabssupports the PR's objective to enhance documentation usability with tabbed interfaces.
14-14: Approved version constraint formyst-nb.The updated version constraint for
myst-nbensures compatibility withsphinxversion 5.0, which is necessary for the project's documentation requirements..github/workflows/website.yml (2)
11-11: Approved branch trigger update.The update to the branch trigger aligns with the specific documentation updates being made in this PR.
61-61: Approved deployment directory update.Setting the
destination_dirtodevelopfor non-main branches is a sensible approach to manage different versions of the documentation.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## develop #1810 +/- ##
===========================================
+ Coverage 73.30% 75.33% +2.02%
===========================================
Files 134 133 -1
Lines 24087 24476 +389
===========================================
+ Hits 17658 18440 +782
+ Misses 6429 6036 -393 ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
Actionable comments posted: 2
Outside diff range, codebase verification and nitpick comments (1)
docs/installation.md (1)
Line range hint
46-58: Suggest simplification for package manager recommendations.The section on using a package manager like Miniforge or Miniconda is informative. However, the note about updating the solver to
libmambain older installations of Anaconda could be simplified to improve clarity.Consider simplifying the instructions on updating the solver to make them more accessible to users who may not be familiar with conda's configuration options.
Tools
LanguageTool
[grammar] ~3-~3: The operating system from Apple is written “macOS”
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...(MAC_OS)
[grammar] ~3-~3: The word ‘install’ is not a noun.
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...(A_INSTALL)
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (1)
- docs/installation.md (6 hunks)
Additional context used
LanguageTool
docs/installation.md
[grammar] ~3-~3: The operating system from Apple is written “macOS”
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...(MAC_OS)
[grammar] ~3-~3: The word ‘install’ is not a noun.
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...(A_INSTALL)
[grammar] ~63-~63: The word ‘install’ is not a noun.
Context: ...nager installation, here are some quick install options: ### Miniforge (recommended) ...(A_INSTALL)
[style] ~417-~417: Consider using “unable” to avoid wordiness.
Context: ...`bash sleap-diagnostic ``` If you were not able to get SLEAP installed, activate the co...(NOT_ABLE_PREMIUM)
Additional comments not posted (5)
docs/installation.md (5)
8-16: Review the conda installation commands.The conda installation commands are well-structured and use the correct channels and package versions. The use of tabs to separate instructions for Windows, Linux, and macOS enhances readability and user experience.
26-42: Validate the terminal opening instructions.The instructions for opening a terminal on different operating systems are clear and include helpful alternatives like Cmder and Windows Terminal for Windows. The use of tabs here is consistent and improves the document's structure.
63-132: Review the Miniforge and Miniconda installation commands.The installation commands for Miniforge and Miniconda are detailed and cover different operating systems, including specific steps for Apple Silicon and Intel Macs. The commands are correctly formatted and provide a comprehensive guide for users.
Tools
LanguageTool
[grammar] ~63-~63: The word ‘install’ is not a noun.
Context: ...nager installation, here are some quick install options: ### Miniforge (recommended) ...(A_INSTALL)
139-259: Assess the structured installation methods.The structured approach to presenting installation methods using tabs is effective and aligns with the PR's objective to enhance readability and usability. The detailed steps for each method, including conda packages, source installations, and pip installations, are well-documented.
Line range hint
263-401: Check the testing and uninstalling instructions.The instructions for testing the installation and uninstalling environments are clear and provide useful commands for users to verify their setups and manage their environments. The use of hints and warnings adds valuable context and guidance.
Tools
LanguageTool
[grammar] ~63-~63: The word ‘install’ is not a noun.
Context: ...nager installation, here are some quick install options: ### Miniforge (recommended) ...(A_INSTALL)
| @@ -1,77 +1,52 @@ | |||
| # Installation | |||
|
|
|||
| SLEAP can be installed as a Python package on Windows, Linux, Mac OS X, and Mac OS Apple Silicon. | |||
| SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For quick install using conda, see below: | |||
There was a problem hiding this comment.
Correct the operating system name and grammar.
The operating system from Apple should be written as "macOS" instead of "Mac OS". Additionally, the phrase "For quick install using conda" should be corrected to "For a quick installation using conda" to use "install" appropriately as a noun.
Apply this diff to correct the issues:
- SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For quick install using conda, see below:
+ SLEAP can be installed as a Python package on Windows, Linux, and macOS. For a quick installation using conda, see below:Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For quick install using conda, see below: | |
| SLEAP can be installed as a Python package on Windows, Linux, and macOS. For a quick installation using conda, see below: |
Tools
LanguageTool
[grammar] ~3-~3: The operating system from Apple is written “macOS”
Context: ...a Python package on Windows, Linux, and Mac OS. For quick install using conda, see bel...(MAC_OS)
[grammar] ~3-~3: The word ‘install’ is not a noun.
Context: ...n Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} ...(A_INSTALL)
| If you were not able to get SLEAP installed, activate the conda environment it is in and generate a list of the package versions installed: | ||
|
|
||
| ```bash | ||
| mamba list | ||
| conda list |
There was a problem hiding this comment.
Improve wording for clarity.
The phrase "If you were not able to get SLEAP installed" could be simplified to "If you were unable to install SLEAP" to avoid wordiness and improve readability.
Apply this diff to improve the wording:
- If you were not able to get SLEAP installed, activate the conda environment it is in and generate a list of the package versions installed:
+ If you were unable to install SLEAP, activate the conda environment it is in and generate a list of the package versions installed:Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| If you were not able to get SLEAP installed, activate the conda environment it is in and generate a list of the package versions installed: | |
| ```bash | |
| mamba list | |
| conda list | |
| If you were unable to install SLEAP, activate the conda environment it is in and generate a list of the package versions installed: | |
| ```bash | |
| conda list | |
| ``` |
Tools
LanguageTool
[style] ~417-~417: Consider using “unable” to avoid wordiness.
Context: ...`bash sleap-diagnostic ``` If you were not able to get SLEAP installed, activate the co...(NOT_ABLE_PREMIUM)
Description
This PR attempts to update and simplify the installation instructions and:
mambacommands withcondamambaandcondacommand interchangeabilityThis PR also attempts to handle the following tasks from
mambaforge is now miniforge-> Recommend miniconda insteadhave 1-line unattended installs-> Link to miniconda installation pageupdate Mac setup to use curl so you don't have to install Xcode (GBs!!)-> Link to miniconda installation pageconda create1-liners in the heading before the TOC!!Types of changes
Does this address any currently open issues?
Outside contributors checklist
Thank you for contributing to SLEAP!
❤️
Summary by CodeRabbit
Documentation
condainstead ofmamba.sphinx_tabsextension and associated settings to enhance tab functionality in documentation.Workflow