[Issue #245] Improve Developer Installation Instructions #247
Conversation
WalkthroughTwo new installation guides for OpenMS have been added to the documentation. One document covers the general installation process for users while the other provides detailed developer installation instructions. Both guides outline prerequisites, step-by-step build procedures (including repository cloning, build directory creation, CMake configuration, compilation using the make command, and optional testing), and include troubleshooting sections for resolving common issues. Changes
Sequence Diagram(s)User Installation ProcesssequenceDiagram
participant U as User
participant Repo as Repository
participant Build as Build System
participant CMake as CMake
participant Make as Make
participant OS as Operating System
U->>Repo: Clone repository
U->>Build: Create build directory
U->>CMake: Configure project
U->>Make: Compile using make
alt Optional tests
U->>Make: Run tests
end
U->>OS: Install OpenMS (may require superuser privileges)
Developer Installation ProcesssequenceDiagram
participant D as Developer
participant Repo as Repository
participant Build as Build System
participant CMake as CMake
participant Make as Make
participant OS as Operating System
D->>Repo: Clone repository
D->>Build: Create build directory
D->>CMake: Configure build environment
D->>Make: Compile using make
alt Optional tests
D->>Make: Run tests
end
D->>OS: Install OpenMS (may require superuser privileges)
Poem
🪧 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
🧹 Nitpick comments (2)
docs/installation.md (1)
54-58: Troubleshooting Section and Toctree Warning
The “Troubleshooting” section provides practical advice on addressing dependency issues and build errors.
- Typographical Note: Although a static analysis tool flagged the use of two consecutive dots (
cmake ..), this is expected behavior for CMake commands.- Pipeline Feedback: The CI pipeline warning that “document isn't included in any toctree” should be addressed by ensuring this new file is added to the documentation TOC if applicable.
Would you like assistance updating the TOC configuration to include this document?
🧰 Tools
🪛 LanguageTool
[typographical] ~56-~56: Two consecutive dots
Context: ...ur PATH. You can verify this by runningcmake ..and checking for any error messages. -...(DOUBLE_PUNCTUATION)
docs/manual/develop/developer-installation.md (1)
58-62: Troubleshooting Section and Consistency Check
The troubleshooting section mirrors that of the general installation guide, providing useful advice on dependency issues and build errors along with a link to the community GitHub Issues page.
- Typographical Note: Similar to the general installation document, the use of two consecutive dots in
cmake ..is intentional.- Pipeline Feedback: Address the CI warning by ensuring this document is referenced in the appropriate TOC if required.
Would you like guidance on updating your documentation configuration to include this file into the TOC?
🧰 Tools
🪛 LanguageTool
[typographical] ~60-~60: Two consecutive dots
Context: ...ur PATH. You can verify this by runningcmake ..and checking for any error messages. -...(DOUBLE_PUNCTUATION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/installation.md(1 hunks)docs/manual/develop/developer-installation.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/installation.md
[typographical] ~56-~56: Two consecutive dots
Context: ...ur PATH. You can verify this by running cmake .. and checking for any error messages. -...
(DOUBLE_PUNCTUATION)
docs/manual/develop/developer-installation.md
[typographical] ~60-~60: Two consecutive dots
Context: ...ur PATH. You can verify this by running cmake .. and checking for any error messages. -...
(DOUBLE_PUNCTUATION)
🪛 GitHub Actions: CI
docs/installation.md
[warning] 1-1: WARNING: document isn't included in any toctree
docs/manual/develop/developer-installation.md
[warning] 1-1: WARNING: document isn't included in any toctree
🔇 Additional comments (17)
docs/installation.md (8)
1-2: Title and File Overview – Approved
The title “Installation Instructions” clearly identifies the document’s purpose for general users.🧰 Tools
🪛 GitHub Actions: CI
[warning] 1-1: WARNING: document isn't included in any toctree
3-11: Prerequisites Section Clarity
The “Prerequisites” section is well structured and provides clear version requirements and helpful download links. This ensures users know exactly which tools they need before proceeding.
12-23: Installation Steps – Clear and Sequential
The step-by-step instructions for installing OpenMS—from cloning the repository to creating a build directory—are clear and logically ordered. The code blocks and commands (such as the Git commands) are correctly formatted and easy to follow.
24-28: Build Directory Creation Instructions
The instructions for creating a build directory are concise and appropriately separated from the source directory, which promotes a cleaner build process.
29-35: Build Configuration with CMake
The “Configure the Build” step usingcmake ..is clearly explained. Note that although the double dot (..) might trigger a typographical hint, it is the correct CMake syntax to reference the parent directory.
36-41: Compilation Process Clarity
The instructions for compiling the project using themakecommand are straightforward. The information about potential compile time based on system performance is useful.
42-47: Optional Test Execution
The “Run Tests” step is clearly marked as optional and provides the appropriate command for running tests. This addition helps ensure users can verify their installation if desired.
48-53: Installation Command and Privilege Instruction
The final installation step, including the use ofsudofor elevated permissions, is properly documented. This ensures that users understand the need for superuser privileges where required.docs/manual/develop/developer-installation.md (9)
1-2: Developer-Focused Title – Approved
The title “Developer Installation Instructions” immediately signals that this document is tailored for developers. The clarity is excellent.🧰 Tools
🪛 GitHub Actions: CI
[warning] 1-1: WARNING: document isn't included in any toctree
3-6: Overview Section Clarity
The “Overview” section succinctly states the purpose of the document. This helps developers quickly understand that the content will cover building OpenMS from source with detailed steps.
7-15: Prerequisites – Detailed and Consistent
The prerequisites listed mirror those in the general installation guide. This consistency is beneficial, and the clear version requirements along with direct download links assist developers in setting up their environments correctly.
16-25: Repository Cloning Instructions
Step 1 (“Clone the Repository”) is well documented with an appropriate code snippet to guide developers through the cloning process.
27-32: Build Directory Setup
The detailed instructions for creating a build directory are clear and encourage good build practices by isolating build files from source code.
34-39: CMake Build Configuration
The instructions for configuring the build using CMake are correctly provided. As with the general installation guide, the use ofcmake ..is standard and correct.
40-45: Compilation Process for Developers
The “Compile the Project” section clearly instructs developers on the usage ofmake. The format and explanation are consistent with prior sections, ensuring no confusion arises.
46-51: Optional Testing Step
The inclusion of an optional step to “Run Tests” is beneficial for developers who wish to verify the integrity of their build. The instructions are straightforward and effectively presented.
52-57: Installation Step – Developer Instructions
The “Install OpenMS” step is clearly detailed, with the necessary command to install OpenMS using superuser privileges. This aligns with standard practices and is presented clearly.
Describe the change
This pull request addresses issue #245 by creating a new
developer-installation.mdfile to provide detailed instructions for developers building OpenMS from source. The updates include:Separation of Instructions: The installation instructions have been split into two distinct files:
installation.md: For general users, covering both precompiled binaries and building from source.developer-installation.md: Specifically for developers, focusing on building from source with detailed prerequisites and troubleshooting.Detailed Developer Guide: The new
developer-installation.mdfile includes:Differences Between
installation.mdanddeveloper-installation.mdPurpose and Audience:
installation.md: Intended for general users, providing a broad overview of installing OpenMS using precompiled binaries or building from source.developer-installation.md: Tailored for developers, focusing on building OpenMS from source with detailed instructions and prerequisites.Content Focus:
installation.md: Includes instructions for both precompiled binaries and building from source, aimed at users seeking a straightforward installation process.developer-installation.md: Focuses solely on building from source, providing detailed guidance for developers.Level of Detail:
installation.md: Offers a concise guide with essential steps for installation.developer-installation.md: Provides a more detailed guide with specific instructions for setting up a development environment.Troubleshooting and Support:
developer-installation.mdoffers more detailed guidance on resolving build errors and dependency issues.These changes aim to make the installation process more accessible and user-friendly for both general users and developers. Please review the changes and let me know if there are any further improvements needed.
PR checklist
CHANGELOG.mdis updated.Summary by CodeRabbit