Merge remote-tracking branch 'refs/remotes/origin/store-more-initial-data' into store-more-initial-data
This commit is contained in:
JoePfeiffer
commit
6b4e7f014e
3
.gitignore
vendored
3
.gitignore
vendored
@ -89,3 +89,6 @@ fabric.properties
|
||||
openrocket.log
|
||||
|
||||
*.snap
|
||||
|
||||
# Sphinx documentation
|
||||
docs/build
|
||||
13
.readthedocs.yaml
Normal file
13
.readthedocs.yaml
Normal file
@ -0,0 +1,13 @@
|
||||
version: "2"
|
||||
|
||||
build:
|
||||
os: "ubuntu-22.04"
|
||||
tools:
|
||||
python: "3.10"
|
||||
|
||||
python:
|
||||
install:
|
||||
- requirements: docs/requirements.txt
|
||||
|
||||
sphinx:
|
||||
configuration: docs/source/conf.py
|
||||
@ -6,6 +6,7 @@ OpenRocket is a free, fully featured model rocket simulator that allows you to d
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
|
||||
[](https://GitHub.com/openrocket/openrocket/releases/)
|
||||
[](https://openrocket.readthedocs.io/en/latest/)
|
||||
|
||||
[](https://snapcraft.io/openrocket)
|
||||
|
||||
@ -36,16 +37,18 @@ OpenRocket is a free, fully featured model rocket simulator that allows you to d
|
||||
|
||||
... plus many more
|
||||
|
||||
📖 Read more on [our website](https://openrocket.info/) or the [OpenRocket Wiki](http://wiki.openrocket.info).
|
||||
📖 Read more on [our website](https://openrocket.info/).
|
||||
|
||||
## 💾 Installers
|
||||
|
||||
You can find the OpenRocket installers [here](https://openrocket.info/downloads.html).
|
||||
|
||||
## 📝 Release Notes
|
||||
|
||||
Release notes are available on each [release's page](https://github.com/openrocket/openrocket/releases) or on [our website](https://openrocket.info/release_notes.html).
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
You can find our documentation on [ReadTheDocs](https://openrocket.readthedocs.io/en/latest/).
|
||||
|
||||
## 🚀 Getting started
|
||||
|
||||
The easiest way to get started is to open one of our in-program example designs:
|
||||
|
||||
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
16
docs/README.md
Normal file
16
docs/README.md
Normal file
@ -0,0 +1,16 @@
|
||||
## Building the docs
|
||||
Install Sphinx and additional dependencies using pip, Python's package manager. Open your command line interface
|
||||
inside the :file:`openrocket/docs` directory and run:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Build the docs by running in the `docs` directory:
|
||||
```bash
|
||||
make html
|
||||
```
|
||||
|
||||
To clean your build (necessary when you change the theme or make other changes to the build configuration), run:
|
||||
```bash
|
||||
make clean
|
||||
```
|
||||
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=source
|
||||
set BUILDDIR=build
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.https://www.sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
4
docs/requirements.txt
Normal file
4
docs/requirements.txt
Normal file
@ -0,0 +1,4 @@
|
||||
sphinx
|
||||
sphinx-rtd-theme
|
||||
sphinx-rtd-dark-mode
|
||||
sphinx_new_tab_link
|
||||
110
docs/source/_static/custom.css
Normal file
110
docs/source/_static/custom.css
Normal file
@ -0,0 +1,110 @@
|
||||
/* Change the ReadTheDocs theme */
|
||||
.wy-nav-content {
|
||||
max-width: 65% !important;
|
||||
}
|
||||
|
||||
.wy-side-nav-search, .wy-nav-top {
|
||||
background: #1d8be1;
|
||||
}
|
||||
|
||||
.wy-side-nav-search .logo {
|
||||
max-width: 42% !important;
|
||||
}
|
||||
|
||||
.seealso .admonition-title {
|
||||
background: #85898c !important;
|
||||
}
|
||||
|
||||
.seealso .admonition-title::before {
|
||||
content: "\f064";
|
||||
margin-right: 0.5em;
|
||||
}
|
||||
|
||||
.seealso {
|
||||
background: #eee !important;
|
||||
}
|
||||
|
||||
.tip .admonition-title::before {
|
||||
content: "\f0eb";
|
||||
margin-right: 0.5em;
|
||||
}
|
||||
|
||||
.note .admonition-title::before {
|
||||
content: "\f05a";
|
||||
margin-right: 0.5em;
|
||||
}
|
||||
|
||||
.warning .admonition-title::before {
|
||||
content: "\f071";
|
||||
margin-right: 0.5em;
|
||||
}
|
||||
|
||||
.attention .admonition-title {
|
||||
background: #e87f7a !important;
|
||||
}
|
||||
|
||||
.attention .admonition-title::before {
|
||||
content: "\f0f3";
|
||||
margin-right: 0.5em;
|
||||
}
|
||||
|
||||
.attention {
|
||||
background: #ffd6cc !important;
|
||||
}
|
||||
|
||||
.admonition-todo {
|
||||
background: #f4ccff !important;
|
||||
}
|
||||
|
||||
.admonition-todo .admonition-title {
|
||||
background: #ff33df !important;
|
||||
}
|
||||
|
||||
.hlist {
|
||||
table-layout: fixed; /* Ensure equals spacing between columns */
|
||||
}
|
||||
|
||||
/* Custom OpenRocket CSS */
|
||||
|
||||
.or-figclass {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.or-image-border img {
|
||||
border: 1px solid #ccc;
|
||||
padding: 3px;
|
||||
}
|
||||
|
||||
.clear-both {
|
||||
clear: both;
|
||||
}
|
||||
|
||||
/* Custom cell classes */
|
||||
.or-table > thead > tr > th {
|
||||
text-align: center;
|
||||
}
|
||||
.or-table > tbody > tr > td:has(.or-table-good) {
|
||||
background-color: #7FFF7F !important; /* Green */
|
||||
}
|
||||
|
||||
.or-table > tbody > tr > td:has(.or-table-okay) {
|
||||
background-color: #FFFF7F !important; /* Yellow */
|
||||
}
|
||||
|
||||
.or-table > tbody > tr > td:has(.or-table-poor) {
|
||||
background-color: #ffac7f !important; /* Orange */
|
||||
}
|
||||
.or-table-cell {
|
||||
color: #2d2d2d;
|
||||
margin: auto !important;
|
||||
text-align: center; !important;
|
||||
}
|
||||
|
||||
.or-table > tbody > tr > td:has(.or-table-bad) {
|
||||
background-color: #FF7F7F !important; /* Red */
|
||||
}
|
||||
|
||||
/* Remove the bottom margin in line blocks in tables */
|
||||
.or-table-line-blocks .line-block {
|
||||
margin-bottom: 0 !important;
|
||||
}
|
||||
BIN
docs/source/_static/navbar-logo.png
Normal file
BIN
docs/source/_static/navbar-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
102
docs/source/conf.py
Normal file
102
docs/source/conf.py
Normal file
@ -0,0 +1,102 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'OpenRocket'
|
||||
copyright = '2024, OpenRocket team'
|
||||
author = 'OpenRocket team'
|
||||
github_url = 'https://github.com/openrocket/openrocket'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '23.09'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinx.ext.duration',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx_new_tab_link',
|
||||
'sphinx_rtd_dark_mode',
|
||||
]
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = []
|
||||
|
||||
# user starts in light mode
|
||||
default_dark_mode = False
|
||||
|
||||
# -- Options for todo extension ----------------------------------------------
|
||||
|
||||
# Show TODOs in the output
|
||||
todo_include_todos = True
|
||||
|
||||
# -- Options for ReadTheDocs -------------------------------------------------
|
||||
|
||||
html_theme_options = {
|
||||
#'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard
|
||||
#'analytics_anonymize_ip': False,
|
||||
'logo_only': False,
|
||||
'display_version': True,
|
||||
'prev_next_buttons_location': 'both',
|
||||
'style_external_links': True,
|
||||
'vcs_pageview_mode': '',
|
||||
# Toc options
|
||||
'collapse_navigation': True,
|
||||
'sticky_navigation': False,
|
||||
'navigation_depth': 3,
|
||||
'includehidden': True,
|
||||
'titles_only': False
|
||||
}
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
html_logo = "_static/navbar-logo.png"
|
||||
|
||||
# Configure Sphinx to update the sidebar whenever the navigation data changes.
|
||||
html_context = {
|
||||
'navigation_update': True
|
||||
}
|
||||
|
||||
html_css_files = [
|
||||
'custom.css',
|
||||
]
|
||||
|
||||
# -- Substitutions -----------------------------------------------------------
|
||||
rst_prolog = """
|
||||
.. |java_vers| replace:: 17
|
||||
.. |br_no_pad| raw:: html
|
||||
|
||||
<div style="line-height: 0; padding: 0; margin: 0"></div>
|
||||
"""
|
||||
4
docs/source/dev_guide/api_documentation.rst
Normal file
4
docs/source/dev_guide/api_documentation.rst
Normal file
@ -0,0 +1,4 @@
|
||||
*****************
|
||||
API Documentation
|
||||
*****************
|
||||
|
||||
110
docs/source/dev_guide/architecture.rst
Normal file
110
docs/source/dev_guide/architecture.rst
Normal file
@ -0,0 +1,110 @@
|
||||
***********************
|
||||
OpenRocket Architecture
|
||||
***********************
|
||||
|
||||
This section describes the high-level architecture of OpenRocket, the important modules and their interactions, and the technology stack.
|
||||
It is intended for developers who want to understand the structure of the code and how it works.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
----
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
OpenRocket is a Java application that runs on the desktop. It is built using the Swing GUI toolkit. The choice of Java
|
||||
was originally made because it is a platform-independent language, making it possible to run OpenRocket on Windows, macOS, and Linux.
|
||||
While the popularity of Java has waned in recent years, it is still a good choice for desktop applications because of its
|
||||
mature libraries and tools. Additionally, rewriting OpenRocket in another language would be a massive undertaking that is
|
||||
not currently feasible given the size of the developer team. Of course, any suggestions and help in this area are welcome.
|
||||
|
||||
OpenRocket is released under the GNU General Public License (GPL) version 3.0. This means that the source code is open and
|
||||
available for anyone to use, modify, and distribute. The only major restriction is that any derivative works must also be
|
||||
released under the GNU GPL. This ensures that the code remains open and free for everyone. So, no one can take the code and
|
||||
sell it as a proprietary product.
|
||||
|
||||
Java Platform Module System (JPMS)
|
||||
==================================
|
||||
|
||||
OpenRocket leverages the **Java Platform Module System** (**JPMS**) to enhance modularity, encapsulation, and maintainability.
|
||||
JPMS allows OpenRocket to be organized into two distinct modules, the ``core`` module and the ``swing`` module,
|
||||
each with its own well-defined boundaries and dependencies.
|
||||
|
||||
Each module in OpenRocket is described by a `module-info.java` file located at the root of the module's source directory
|
||||
(:file:`<module>/src/main/java.module-info.java`). This file declares:
|
||||
|
||||
* **Module Name:** A unique identifier for the module (e.g., `info.openrocket.core`, `info.openrocket.swing`).
|
||||
* **Dependencies:** The modules that this module depends on to function correctly. For example, the `info.openrocket.swing` module depends on the `info.openrocket.core` module.
|
||||
* **Exported Packages:** The packages within the module that are accessible to other modules.
|
||||
* **Services:** The services provided or consumed by the module (if applicable).
|
||||
|
||||
By embracing JPMS, OpenRocket gains several advantages:
|
||||
|
||||
* **Strong Encapsulation:** Modules explicitly control what packages are exposed, preventing accidental access to internal implementation details.
|
||||
* **Reliable Configuration:** The module system verifies dependencies at compile time and runtime, reducing the risk of missing or incompatible components.
|
||||
* **Improved Maintainability:** Modules can be developed and tested independently, making it easier to understand, modify, and evolve the codebase.
|
||||
* **Scalability:** The modular structure facilitates the addition of new features or the replacement of existing components without impacting the entire application.
|
||||
|
||||
|
||||
Core Module
|
||||
===========
|
||||
|
||||
The ``core`` module contains the core functionality of OpenRocket, such as the rocket simulation engine, the file format
|
||||
parsers and writers, and the rocket design classes. This module is intended to be reusable and can be used in other
|
||||
applications that need rocket simulation capabilities.
|
||||
|
||||
Swing Module
|
||||
============
|
||||
|
||||
The ``swing`` module contains the user interface of OpenRocket. It is built using the Swing GUI toolkit and provides a graphical
|
||||
interface for designing rockets, running simulations, and viewing the results. This module depends on the core module
|
||||
and uses its functionality to perform the simulations and display the results.
|
||||
|
||||
Rocket Components
|
||||
=================
|
||||
|
||||
|
||||
|
||||
Aerodynamic Calculators and Simulators
|
||||
======================================
|
||||
|
||||
Simulation Listeners
|
||||
====================
|
||||
|
||||
|
||||
Component Database
|
||||
==================
|
||||
|
||||
Thrust Curves
|
||||
=============
|
||||
|
||||
:abbr:`OR (OpenRocket)` uses Thrustcurves.org for its thrustcurves/motors.
|
||||
|
||||
Scripts
|
||||
=======
|
||||
|
||||
Plugins
|
||||
=======
|
||||
|
||||
File Format (.ork)
|
||||
==================
|
||||
|
||||
The OpenRocket native format uses the file extension \*.ork. It is an XML format file combined with any needed graphics
|
||||
files, contained in a ZIP archive. The extension \*.ork.gz is also accepted by OpenRocket, though plain .ork is recommended.
|
||||
In other to view the contents of the file, you can simply rename the file extension to .zip and extract the contents.
|
||||
|
||||
|
||||
The ``version`` attribute of the <openrocket> tag describes the file format version used, while the ``creator``
|
||||
attribute *may* describe the software and version used to write the document. The file format version is increased
|
||||
every time the format is changed. The minor number is increased when changes are made that are mostly backward-compatible,
|
||||
meaning that older software versions should be able to read the design sans the new features. The major number is
|
||||
increased when changes are made that render the design problematic or impossible to read for older software. For maximum
|
||||
compatibility software should save a file in the oldest file format version that supports all the necessary design features.
|
||||
|
||||
For an overview of the changes between file format versions, see the `fileformat.txt <https://github.com/openrocket/openrocket/blob/unstable/fileformat.txt>`_
|
||||
file in the root directory of the repository.
|
||||
|
||||
|
||||
|
||||
287
docs/source/dev_guide/building_releasing.rst
Normal file
287
docs/source/dev_guide/building_releasing.rst
Normal file
@ -0,0 +1,287 @@
|
||||
**********************
|
||||
Building and Releasing
|
||||
**********************
|
||||
|
||||
This guide explains the build system of OpenRocket (Gradle), and how to release a new version of OpenRocket.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
----
|
||||
|
||||
Gradle
|
||||
======
|
||||
|
||||
`Gradle <http://www.gradle.org/>`__ is the build system for OpenRocket. It is used to compile the source code, run tests, and create the JAR file.
|
||||
Key features of Gradle are:
|
||||
|
||||
- **Incremental builds**: Gradle only rebuilds what is necessary, which makes the build process faster.
|
||||
|
||||
- **Dependency management**: Gradle has a robust dependency management system capable of handling project and third-party libraries.
|
||||
|
||||
- **Performance**: Gradle uses techniques like build caching and parallel execution to improve performance of the build process.
|
||||
|
||||
The root directory of the OpenRocket repository contains several Gradle files:
|
||||
|
||||
- ``build.gradle``: This is the main build script file where you define your project configuration and tasks such as compile and run tasks, dependency management, plugins usage, and more.
|
||||
|
||||
- ``settings.gradle``: Used for multi-project build configurations to include which sub-projects should be part of the build.
|
||||
For OpenRocket, this file is used to identify the ``core`` and ``swing`` sub-projects.
|
||||
|
||||
- ``gradle.properties``: Contains project-wide properties that can be accessed from the build script. For example, the version number of OpenRocket can be defined here.
|
||||
|
||||
- ``gradlew`` and ``gradlew.bat``: These are Gradle Wrapper scripts for Unix-based and Windows systems respectively.
|
||||
It allows users to run Gradle builds without requiring Gradle to be installed on the system.
|
||||
|
||||
The ``core`` and ``swing`` sub-projects contain their own ``build.gradle`` and ``gradle.properties`` files that define the tasks specific to those sub-projects.
|
||||
|
||||
Gradle in IntelliJ
|
||||
------------------
|
||||
|
||||
If you use IntelliJ IDEA, you can access the Gradle tasks within the IDE. First, open the Gradle tool window by going to
|
||||
:menuselection:`View --> Tool Windows --> Gradle` or by clicking on the Gradle icon in the right-hand side of the window:
|
||||
|
||||
.. figure:: /img/dev_guide/building_releasing/gradle_in_intellij.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Opening the Gradle tool window in IntelliJ IDEA.
|
||||
|
||||
Opening the Gradle tool window in IntelliJ IDEA.
|
||||
|
||||
This shows the following window:
|
||||
|
||||
.. figure:: /img/dev_guide/building_releasing/intellij_gradle_window.png
|
||||
:align: center
|
||||
:width: 30%
|
||||
:alt: The Gradle tool window in IntelliJ IDEA.
|
||||
|
||||
The Gradle tool window in IntelliJ IDEA.
|
||||
|
||||
Here's a breakdown of the Gradle tasks:
|
||||
|
||||
- *info.openrocket*: the root project
|
||||
- *Tasks*: Gradle tasks specific to the root project.
|
||||
- *application*: Contains tasks related to running or debugging your application from within the IDE.
|
||||
- *build*: Includes tasks for building the entire project.
|
||||
- *build setup*: Tasks for initializing a new Gradle build, such as creating new Gradle files.
|
||||
- *distribution*: Tasks for assembling the application distribution, like creating zips or tarballs of the build outputs.
|
||||
- *documentation*: Tasks for generating documentation, typically using tools like Javadoc.
|
||||
- *help*: Provides tasks that list other tasks or project properties.
|
||||
- *info.openrocket*: Custom tasks specific to the 'info.openrocket' module.
|
||||
- *other*: Any other tasks that do not fit into the predefined categories.
|
||||
- *shadow*: Related to the Shadow plugin, which packages the project’s artifacts along with its dependencies into a single "fat" JAR.
|
||||
- *verification*: Tasks for testing and verifying the project, such as running unit tests.
|
||||
- *Dependencies*: Lists the dependencies of the project.
|
||||
- *Run Configurations*: Gradle run configurations that can be used in IntelliJ.
|
||||
- *core*: the core module
|
||||
- *Tasks*: Gradle tasks specific to the 'core' module.
|
||||
- *Dependencies*: Lists the dependencies of the 'core' module.
|
||||
- *swing*: the swing module
|
||||
- *Tasks*: Gradle tasks specific to the 'swing' module.
|
||||
- *Dependencies*: Lists the dependencies of the 'swing' module.
|
||||
|
||||
Most Important Gradle Tasks
|
||||
---------------------------
|
||||
|
||||
Here are some of the most important Gradle tasks for OpenRocket:
|
||||
|
||||
.. list-table:: Most Important Gradle Tasks
|
||||
:widths: 25 25 50
|
||||
:header-rows: 1
|
||||
|
||||
* - Module
|
||||
- Task
|
||||
- Description
|
||||
|
||||
* - root (*info.openrocket*)
|
||||
- ``clean``
|
||||
- Deletes the build directory and all its contents (basically cleans up the project).
|
||||
|
||||
* - root (*info.openrocket*)
|
||||
- ``run``
|
||||
- Runs the OpenRocket application.
|
||||
|
||||
* - root (*info.openrocket*)
|
||||
- ``check``
|
||||
- Runs the unit tests and checks the code quality using the Checkstyle static analysis tool.
|
||||
|
||||
* - root (*info.openrocket*)
|
||||
- ``build``
|
||||
- Compiles the source code, runs the unit tests, and creates the JAR file for the *core* and *swing* module.
|
||||
|
||||
* - root (*info.openrocket*)
|
||||
- ``dist``
|
||||
- Creates a distributable JAR file of OpenRocket (a combination of the *core* and *swing* JAR) at :file:`openrocket/build/libs/OpenRocket-<build-version>.jar`.
|
||||
|
||||
* - core
|
||||
- ``serializeEngines``
|
||||
- Fetch the latest thrust curves from ThrustCurve.org and serialize them to the OpenRocket format. The resulting serialized file is saved in the ``src`` dir so it can be used for a build.
|
||||
|
||||
* - core
|
||||
- ``serializeEnginesDist``
|
||||
- Same as ``serializeEngines``, but loads the serialized file to the distribution directory (:file:`openrocket/build`) so it can be used in the final build.
|
||||
|
||||
* - core
|
||||
- ``submoduleUpdate``
|
||||
- Updates the submodule dependencies of the *core* module.
|
||||
|
||||
You can run these tasks from the command line using the Gradle Wrapper scripts. For example for the task ``run``, run the
|
||||
following command in the root directory of the OpenRocket repository:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# On macOS and Linux:
|
||||
./gradlew run
|
||||
|
||||
# On Windows:
|
||||
gradlew.bat run
|
||||
|
||||
install4j
|
||||
=========
|
||||
|
||||
`install4j <http://www.ej-technologies.com/products/install4j/overview.html>`__ is used to create the packaged installers for OpenRocket from the JAR file.
|
||||
install4j generously provides a free license for open source projects, including OpenRocket. Currently, only the OpenRocket administrators have access
|
||||
to the install4j license.
|
||||
|
||||
Code Signing
|
||||
------------
|
||||
|
||||
An important part of generating the installers is `code signing <https://en.wikipedia.org/wiki/Code_signing>`__.
|
||||
This is done to ensure that the installer is not tampered with between the time it is created and the time it is run by the user.
|
||||
Once the OpenRocket installer has been code signed, users will receive no more (or the minimum amount of) warnings from
|
||||
their operating system that the installer is from an unknown source and may contain malware.
|
||||
More information on how to do code signing in install4j can be found `here <https://www.ej-technologies.com/resources/install4j/help/doc/concepts/codeSigning.html>`__.
|
||||
|
||||
Only the OpenRocket administrators have access to the code signing certificates.
|
||||
|
||||
Code signing for Windows is done using a digital certificate from Sectigo. More information on the code signing procedure,
|
||||
including whitelisting OpenRocket by Microsoft, see the `README file on GitHub <https://github.com/openrocket/openrocket/blob/unstable/install4j/README.md>`__.
|
||||
|
||||
For macOS, the code signing is done using an Apple Developer ID. Besides code signing, the OpenRocket app also needs to
|
||||
be notarized. Luckily, install4j takes care of this. More information on the code signing procedure for macOS can be found in the
|
||||
`README file on GitHub <https://github.com/openrocket/openrocket/blob/unstable/install4j/README.md>`__.
|
||||
|
||||
Linux does not require code signing.
|
||||
|
||||
Creating the Installers
|
||||
-----------------------
|
||||
|
||||
First you need to build the project using Gradle (see above). This will create the JAR file that will be used to create the installers.
|
||||
|
||||
Then, open install4j (requires a license) and load the project file *openrocket/install4j/<build-version>/openrocket-<build-version>.install4j*
|
||||
from the repository. Go to the :menuselection:`Build` tab and click on the :guilabel:`Start Build` button. This will create the installers in
|
||||
the *openrocket/install4j/<build-version>/media/* directory.
|
||||
|
||||
.. figure:: /img/dev_guide/building_releasing/install4j_build.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Building the installers in install4j.
|
||||
|
||||
Building the installers in install4j.
|
||||
|
||||
If you do not have access to the code signing certificates, you can create the installers without code signing by
|
||||
enabling the checkboxes ``Disable code signing`` and ``Disable notarization`` in the ``Build`` tab.
|
||||
|
||||
Release Procedure
|
||||
=================
|
||||
|
||||
The release procedure for OpenRocket is as follows:
|
||||
|
||||
1. Update the `ReleaseNotes.md <https://github.com/openrocket/openrocket/blob/unstable/ReleaseNotes.md>`__ with the changes that are part of the new release.
|
||||
This includes new features, bug fixes, and other changes that are part of the release. Make sure to include the version number and the release date.
|
||||
Take a look at the previous release notes to see how it should be formatted.
|
||||
|
||||
2. Update the component database and thrustcurves by running the gradle tasks ``subModuleUpdate`` and ``serializeEnginesDist`` respectively.
|
||||
|
||||
3. **Update the version number** in ``openrocket/core/src/main/resources/build.properties`` to the correct version number.
|
||||
|
||||
For official releases, the version number should use the format ``YY.MM`` (*year.month*). For example, if the software is released in
|
||||
September 2023, the version number should be ``23.09``. If there are multiple releases in the same month, add an incremental number
|
||||
to the version number, e.g. ``23.09.01``.
|
||||
|
||||
If a new release contains significant changes, it may be necessary to release alpha or beta versions first. In that case, the version
|
||||
number should be appended with ``.alpha.`` or ``.beta.`` plus an incremental number. For example, if the software is in beta stage
|
||||
in September 2023, the version number should be ``23.09.beta.01``. In general, alpha releases are not necessary. This is only for very rough releases.
|
||||
Beta releases are only necessary if there are significant changes that need to be tested by the community before the final release.
|
||||
|
||||
One final option is to release a release candidate (RC) version. This is a version that is considered to be the final version,
|
||||
but needs to be tested by the community before the final release. The version number should be appended with ``.RC.`` plus an incremental number.
|
||||
For example, if the software is in RC stage in September 2023, the version number should be ``23.09.RC.01``.
|
||||
|
||||
The official release that comes after the beta release should have the same version number as the beta release, but without the ``.beta.`` part.
|
||||
For instance, if the beta testing started in September 2023 with version number ``23.09.beta.01``, the final release should have version number ``23.09``,
|
||||
even if the final release is in November 2023. This is to ensure consistency in the version numbering and to link the beta release(s) to the final release.
|
||||
|
||||
4. **Build the project JAR file** using Gradle (see above).
|
||||
|
||||
5. **Test the JAR file** to ensure that it works correctly and that the new version number is applied to the splash screen and under :menuselection:`Help --> About`.
|
||||
|
||||
6. **Create the packaged installers** using install4j (see above).
|
||||
|
||||
.. warning::
|
||||
Make sure to **enable code signing** for the installers.
|
||||
|
||||
Make sure that `DS_Store <https://github.com/openrocket/openrocket/blob/unstable/install4j/23.09/macOS_resources/DS_Store>`__ for the macOS
|
||||
installer is updated. Instructions can be found `here <https://github.com/openrocket/openrocket/blob/unstable/install4j/README.md>`__.
|
||||
|
||||
7. **Test the installers** to ensure that they work correctly.
|
||||
|
||||
8. **Prepare the website** *(for official releases only, not for alpha, beta, or release candidate releases)*.
|
||||
|
||||
The `source code for the website <https://github.com/openrocket/openrocket.github.io>`__ needs to be updated to point to the new release.
|
||||
Follow these steps:
|
||||
|
||||
- Add the release to `downloads_config.json <https://github.com/openrocket/openrocket.github.io/blob/development/assets/downloads_config.json>`__.
|
||||
- Update the ``current_version`` in `_config <https://github.com/openrocket/openrocket.github.io/blob/development/_config.yml>`__.
|
||||
- Add a new entry to `_whats_new <https://github.com/openrocket/openrocket.github.io/tree/development/_whats-new>`__ for the new release.
|
||||
Create a ``wn-<version number>.md`` file with the changes that are part of the new release. Please take a close look to the previous entries to see how it should be formatted.
|
||||
- Update the `release notes <https://github.com/openrocket/openrocket.github.io/blob/development/_includes/ReleaseNotes.md>`__
|
||||
(which is a link to the What's new file that you just created). Again, take a close look at the previous entries to see how it should be formatted.
|
||||
|
||||
.. warning::
|
||||
Make sure to **update the website on the** ``development`` **branch**. The ``master`` branch is the branch that is live
|
||||
on the website. First update the ``development`` branch and test the changes on the website. In a later step, the
|
||||
changes will be merged to the ``master`` branch.
|
||||
|
||||
9. **Publish the release on GitHub**.
|
||||
|
||||
Go to the `releases page <https://github.com/openrocket/openrocket/releases>`__. Click *Draft a new release*.
|
||||
Select *Choose a tag* and enter a new tag name, following the format ``release-<version number>``, e.g. ``release-23.09``.
|
||||
The title should follow the format ``OpenRocket <version number> (<release date as YYYY-MM-DD>)``, e.g. ``OpenRocket 23.09 (2023-11-16)``.
|
||||
|
||||
Fill in the release text, following the `ReleaseNotes.md <https://github.com/openrocket/openrocket/blob/unstable/ReleaseNotes.md>`__.
|
||||
If you want to credit the developers who contributed to the release, you can tag them anywhere in the release text using the `@username` syntax.
|
||||
They will then be automatically displayed in the contributors list on the release page.
|
||||
|
||||
Finally, upload all the packaged installers and the JAR file to the release. The source code (zip and tar.gz) is
|
||||
automatically appended to each release, you do not need to upload it manually.
|
||||
|
||||
If this is an alpha, beta, or release candidate release, tick the *Set as a pre-release* checkbox.
|
||||
|
||||
Click *Publish release*.
|
||||
|
||||
10. **Push the changes to the website**
|
||||
|
||||
First, build the ``development`` branch locally to verify that the changes that you made in step 8 are correct.
|
||||
If everything is working (test the download links, the release notes, and the What's new page), create a new PR
|
||||
that merges the changes from the ``development`` branch to the ``master`` branch.
|
||||
|
||||
11. **Send out the release announcement**.
|
||||
|
||||
Send out the release announcement to the OpenRocket mailing list, the TRF forum, and the OpenRocket social media channels
|
||||
(Discord, Facebook...).
|
||||
|
||||
The announcement should include the new features, bug fixes, and other changes that are part of the new release.
|
||||
Make sure to include the download links to the new release. Here is an `example announcement <https://www.rocketryforum.com/threads/announcement-openrocket-23-09-is-now-available-for-download.183186/>`__.
|
||||
|
||||
12. **Merge the** ``unstable``` **branch to the** ``master``` **branch**.
|
||||
|
||||
After the release is published, merge the changes from the `unstable <https://github.com/openrocket/openrocket>`__ branch
|
||||
to the `master <https://github.com/openrocket/openrocket/tree/master>`__ branch.
|
||||
|
||||
13. **Upload the new release to** `SourceForge <https://sourceforge.net/projects/openrocket/>`__.
|
||||
|
||||
The downloads page on SourceForge is still very actively used, so be sure to upload the new release there as well.
|
||||
|
||||
14. **Update package managers** (e.g. snap, Chocolatey, Homebrew) with the new release.
|
||||
201
docs/source/dev_guide/codebase_walkthrough.rst
Normal file
201
docs/source/dev_guide/codebase_walkthrough.rst
Normal file
@ -0,0 +1,201 @@
|
||||
********************
|
||||
Codebase Walkthrough
|
||||
********************
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
:backlinks: none
|
||||
|
||||
----
|
||||
|
||||
Important Modules and Packages
|
||||
==============================
|
||||
|
||||
Root Directory Structure
|
||||
========================
|
||||
|
||||
|
||||
|
||||
Module Folder Structure
|
||||
=======================
|
||||
|
||||
OpenRocket uses the Gradle build system, where each modules (``info.openrocket.core`` and ``info.openrocket.swing``) adheres to the following folder structure:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
├── gradle # Gradle Wrapper
|
||||
├── libs # (optional) Library JAR files that cannot be obtained from the gradle dependency system
|
||||
├── resources-src # Source files for the resources in the src dir (e.g. InkScape project file for the splash screen)
|
||||
├── scripts # Utility scripts
|
||||
├── src # Source code and resources
|
||||
│ ├── main # Application source code and resources
|
||||
│ │ ├── java # Java source code
|
||||
│ │ ├── resources # Resource files (e.g. images, configuration files, data files)
|
||||
│ ├── test # Test source code and resources
|
||||
│ │ ├── java # Java test source code
|
||||
│ │ ├── resources # Resource files for testing
|
||||
├── src-extra # Extra source code, not part of the main application (e.g. template code for an OpenRocket plugin)
|
||||
|
||||
Core Module
|
||||
-----------
|
||||
|
||||
The following is an overview of the packages in the ``info.openrocket.core`` module (:file:`openrocket/core/src/main/java/info/openrocket/core`):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
├── aerodynamics # Calculation of aerodynamic properties (e.g. aerodynamic forces, CD)
|
||||
│ └── barrowman # Barrowman method for calculating aerodynamic properties
|
||||
├── appearance # Appearance of components (e.g. color, texture)
|
||||
│ └── defaults # Default appearance settings
|
||||
├── arch # Get info on the system architecture (macOS, Windows, Linux)
|
||||
├── communication # Communication with external sites/programs (e.g. retrieve the latest version of OpenRocket from GitHub)
|
||||
├── database # Database handling (component database, motor database)
|
||||
│ └── motor # Thrust curve (i.e. motor) database
|
||||
├── document # OpenRocket document and simulation handling
|
||||
│ ├── attachments # Attachments to OpenRocket documents
|
||||
│ └── events # OpenRocket events (i.e. document changed, simulation changed)
|
||||
├── file # File handling
|
||||
│ ├── iterator # Iterate files in e.g. a directory or a zip file
|
||||
│ ├── motor # Motor files handling
|
||||
│ ├── openrocket # OpenRocket file handling
|
||||
│ │ ├── importt # Import OpenRocket files
|
||||
│ │ └── savers # Save OpenRocket files
|
||||
│ ├── rasaero # RASAero II file handling
|
||||
│ │ ├── export # Export OpenRocket files to RASAero II
|
||||
│ │ └── importt # Import RASAero II files to OpenRocket
|
||||
│ ├── rocksim # RockSim file handling
|
||||
│ │ ├── export # Export OpenRocket files to RockSim
|
||||
│ │ └── importt # Import RockSim files to OpenRocket
|
||||
│ ├── simplesax # XML file handling
|
||||
│ ├── svg # SVG file handling
|
||||
│ │ └── export # SVG export
|
||||
│ └── wavefrontobj # Wavefront OBJ file handling
|
||||
│ └── export # Export OpenRocket components to Wavefront OBJ
|
||||
│ ├── components # Export OpenRocket components
|
||||
│ └── shapes # Export general geometry shapes
|
||||
├── formatting # Formatting of e.g. motor config names
|
||||
├── gui
|
||||
│ └── util # Filename filter
|
||||
├── l10n # Localization (translation of OpenRocket into languages other than English)
|
||||
├── logging # Errors, warnings, and aborts
|
||||
├── masscalc # Mass property (e.g. mass, CG, moments of inertia) calculation drivers. Actual component mass calculations are in the components themselves
|
||||
├── material # Material properties (physical properties of materials)
|
||||
├── models # Physical models (e.g. atmosphere, gravity, wind)
|
||||
│ ├── atmosphere # Atmosphere models
|
||||
│ ├── gravity # Gravity models
|
||||
│ └── wind # Wind models
|
||||
├── motor # Motor configuration, ID, and thrustcurves
|
||||
├── optimization # Optimization algorithms
|
||||
│ ├── general # Parameter search space algorithms
|
||||
│ │ ├── multidim # Multidimensional parallel search optimization
|
||||
│ │ └── onedim # One dimensional golden-section search optimization
|
||||
│ ├── rocketoptimization # Optimization of rocket parameters for specified goal functions
|
||||
│ │ ├── domains # Limits on optimization parameters
|
||||
│ │ ├── goals # Max, min, and specific value optimization goals
|
||||
│ │ ├── modifiers # Modify rocket parameters
|
||||
│ │ └── parameters # Simulation results that can be optimized
|
||||
│ └── services # Provide parameters etc to optimizer
|
||||
├── plugin # Plugin interface (more general but less developed than extension interface)
|
||||
├── preset # Component presets
|
||||
│ ├── loader # Component database file loader
|
||||
│ └── xml # Component database file writer
|
||||
├── rocketcomponent # Rocket components (e.g. fins, nose cone, tube)
|
||||
│ └── position # Position of rocket components
|
||||
├── rocketvisitors # Create lists of components and motors
|
||||
├── scripting # Javascript scripting of OR functionality
|
||||
├── simulation # Flight simulation code
|
||||
│ ├── customexpression # User defined custom expression handling
|
||||
│ ├── exception # Exceptions occurring during simulation
|
||||
│ ├── extension # User defined simulation extensions
|
||||
│ │ ├── example # Examples of simulation extensions
|
||||
│ │ └── impl # Helper methods for implementing extensions
|
||||
│ └── listeners # Code "listening" to simulation to implement functionality
|
||||
│ ├── example # Example user listeners
|
||||
│ └── system # Listeners used by OpenRocket itself
|
||||
├── startup # Root Application and related classes
|
||||
├── thrustcurve # Thrustcurve file and thrustcurve.org API
|
||||
├── unit # Definitions of units and unit conversions
|
||||
├── util # Miscellaneous utility methods
|
||||
│ └── enums # Conversion of enums to names
|
||||
└── utils # More utility methods
|
||||
|
||||
|
||||
Swing Module
|
||||
------------
|
||||
|
||||
The following is an overview of the packages in the ``info.openrocket.swing`` module (*openrocket/swing/src/main/java/info/openrocket/swing*):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
├── communication
|
||||
├── file
|
||||
│ ├── motor
|
||||
│ ├── photo
|
||||
│ └── wavefrontobj
|
||||
├── gui
|
||||
│ ├── adaptors
|
||||
│ ├── components
|
||||
│ │ └── compass
|
||||
│ ├── configdialog
|
||||
│ ├── customexpression
|
||||
│ ├── dialogs
|
||||
│ │ ├── flightconfiguration
|
||||
│ │ ├── motor
|
||||
│ │ │ └── thrustcurve
|
||||
│ │ ├── optimization
|
||||
│ │ ├── preferences
|
||||
│ │ └── preset
|
||||
│ ├── figure3d
|
||||
│ │ ├── geometry
|
||||
│ │ └── photo
|
||||
│ │ ├── exhaust
|
||||
│ │ └── sky
|
||||
│ │ └── builtin
|
||||
│ ├── figureelements
|
||||
│ ├── help
|
||||
│ │ └── tours
|
||||
│ ├── main
|
||||
│ │ ├── componenttree
|
||||
│ │ └── flightconfigpanel
|
||||
│ ├── plot
|
||||
│ ├── preset
|
||||
│ ├── print
|
||||
│ │ ├── components
|
||||
│ │ └── visitor
|
||||
│ ├── rocketfigure
|
||||
│ ├── scalefigure
|
||||
│ ├── simulation
|
||||
│ ├── theme
|
||||
│ ├── util
|
||||
│ ├── watcher
|
||||
│ └── widgets
|
||||
├── logging
|
||||
├── simulation
|
||||
│ └── extension
|
||||
│ ├── example
|
||||
│ └── impl
|
||||
├── startup
|
||||
│ ├── jij
|
||||
│ └── providers
|
||||
└── utils
|
||||
|
||||
Units used in OpenRocket
|
||||
========================
|
||||
|
||||
OpenRocket always uses internally pure SI units. For example all rocket dimensions and flight distances are in meters, all
|
||||
masses are in kilograms, density is in kg/m³, temperature is in Kelvin etc. This convention is also used when storing the
|
||||
design in the OpenRocket format.
|
||||
|
||||
The only exception to this rule is angles:
|
||||
|
||||
- Angles are represented as radians internally, but in the file format they are converted to degrees. This is to make
|
||||
the file format more human-readable and to avoid rounding errors.
|
||||
|
||||
- Latitude and longitude of the launch site are represented in degrees both internally and externally.
|
||||
|
||||
When displaying measures to the user, the values are converted into the preferred units of the user. This is performed
|
||||
using classes in the package ``info.openrocket.core.unit``. The ``Unit`` class represents a single unit and it includes methods for
|
||||
converting between that unit and SI units in addition to creating a string representation with a suitable amount of decimals.
|
||||
A ``UnitGroup`` describes a measurable quantity such as temperature and contains the units available for that quantity,
|
||||
such as Celsius, Fahrenheit and Kelvin.
|
||||
399
docs/source/dev_guide/contributing_to_the_docs.rst
Normal file
399
docs/source/dev_guide/contributing_to_the_docs.rst
Normal file
@ -0,0 +1,399 @@
|
||||
*********************************
|
||||
Contributing to the Documentation
|
||||
*********************************
|
||||
|
||||
This document explains how to contribute to the OpenRocket documentation. It provides information on why we use Sphinx
|
||||
for our documentation, how to edit and build the documentation, and the style guide for writing documentation.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
:backlinks: none
|
||||
|
||||
----
|
||||
|
||||
Why Sphinx?
|
||||
===========
|
||||
|
||||
This documentation is generated using `Sphinx <https://www.sphinx-doc.org/en/master/>`__. Sphinx is a tool that makes it
|
||||
easy to create intelligent and beautiful documentation. It is used by many open-source projects, including
|
||||
`Python <https://www.python.org/>`__, `NumPy <https://numpy.org/>`__, and `Matplotlib <https://matplotlib.org/>`__.
|
||||
Sphinx uses `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ as its markup language, which is a lightweight markup language that is easy to read and write. Sphinx also supports `Markdown <https://www.markdownguide.org/>`__ and `LaTeX <https://www.latex-project.org/>`__.
|
||||
|
||||
Previously, OpenRocket used MediaWiki for its documentation, but we decided to switch to Sphinx for several reasons:
|
||||
|
||||
- Sphinx is more powerful, modern, and flexible than MediaWiki. It allows us to create more complex and interactive documentation.
|
||||
|
||||
- Sphinx is easier to maintain than MediaWiki. It is easier to update and manage the documentation in the source files.
|
||||
|
||||
- Sphinx can give warnings and errors when building the documentation, which helps to catch mistakes and inconsistencies.
|
||||
|
||||
- The documentation is hosted on our GitHub repository, together with the source code. This ensures all resources are concentrated,
|
||||
makes it easier to keep the documentation in sync with the code, and allows for better version control.
|
||||
|
||||
- Lastly, for some users who wanted to contribute to the MediaWiki documentation, their access to the MediaWiki was blocked.
|
||||
We were never able to solve that issue.
|
||||
|
||||
Read the Docs
|
||||
-------------
|
||||
|
||||
The OpenRocket documentation is hosted on `Read the Docs <https://readthedocs.org/>`__. Read the Docs is a popular
|
||||
platform for hosting documentation for open-source projects. It automatically builds the documentation from the source
|
||||
files in the OpenRocket repository and makes it available online. This makes it easy for users to access the documentation
|
||||
and for contributors to update it. It also supports versioning, so you can view the documentation for different versions of
|
||||
OpenRocket, and it has a search feature that allows you to quickly find what you are looking for. Additionally, you can also
|
||||
add translations to the documentation, which makes it accessible to a wider audience.
|
||||
|
||||
----
|
||||
|
||||
Editing and Building the Documentation
|
||||
======================================
|
||||
|
||||
If you would like to contribute to the documentation, you can do so by editing the reStructuredText files in the
|
||||
:file:`docs/source` directory of the OpenRocket repo. You can then build the documentation by first
|
||||
`installing Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`__ and some extra dependencies.
|
||||
Open a new terminal window in the :file:`docs` directory and run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install -r requirements.txt
|
||||
|
||||
To build the docs, run the following command from the ``docs`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make html
|
||||
|
||||
This will generate the documentation in the :file:`docs/build/html` directory. You can then view the documentation by opening the
|
||||
``index.html`` file in your web browser.
|
||||
|
||||
To clean your build (necessary when you change the theme or make other changes to the build configuration), run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make clean
|
||||
|
||||
|
||||
If you would like to contribute to the documentation, please submit a pull request with your changes. If you are not sure how to
|
||||
do this, please see the ``Obtaining the Source Code`` section in :doc:`Development Environment Setup </dev_guide/development_setup>`.
|
||||
Also check out the `GitHub documentation <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`__
|
||||
on how to submit a pull request. If you don't want to go through the hassle of setting up a development environment, you can also
|
||||
`submit an issue <https://github.com/openrocket/openrocket/issues/new/choose>`__ with your proposed changes and we will take care of the rest,
|
||||
or you can `contact us <https://openrocket.info/contact.html>`__.
|
||||
|
||||
----
|
||||
|
||||
Style Guide
|
||||
===========
|
||||
|
||||
This section provides a style guide for writing documentation for OpenRocket. It covers conventions that we use in the docs
|
||||
and useful tips for writing reStructuredText/Sphinx docs.
|
||||
|
||||
.. _heading_levels:
|
||||
|
||||
Heading levels
|
||||
--------------
|
||||
|
||||
Normally, in reStructuredText, there are no heading levels assigned to certain characters as the structure is determined
|
||||
from the succession of headings. However, we have set the following heading level rules for the documentation:
|
||||
|
||||
- \# with overline, for parts *(not really used at the moment)*
|
||||
|
||||
- \* with overline, for chapters
|
||||
|
||||
- \= for sections
|
||||
|
||||
- \- for subsections
|
||||
|
||||
- \^ for subsubsections
|
||||
|
||||
- \" for paragraphs
|
||||
|
||||
Note that the overline and underline characters must be the same length as the text they are underlining.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
*****************************************
|
||||
H1: This is a chapter (title of the page)
|
||||
*****************************************
|
||||
|
||||
H2: This is a section
|
||||
=====================
|
||||
|
||||
H3: This is a subsection
|
||||
------------------------
|
||||
|
||||
H4: This is a subsubsection
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
H5: This is a paragraph
|
||||
"""""""""""""""""""""""
|
||||
|
||||
Horizontal Rules
|
||||
----------------
|
||||
|
||||
Horizontal rules are used to separate sections of the documentation. They are created using four or more hyphens (----).
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
This is a section
|
||||
=================
|
||||
|
||||
----
|
||||
|
||||
This is another section
|
||||
=======================
|
||||
|
||||
.. note::
|
||||
|
||||
As seen in the example, it is recommended to **always add a horizontal rule before starting a new section**
|
||||
(H2, see :ref:`Heading levels <heading_levels>`).
|
||||
|
||||
Adding Images
|
||||
-------------
|
||||
|
||||
Images are added to the documentation like this:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. figure:: /img/path/to/your/image.png
|
||||
:width: 50% (please always express this as a percentage, and don't go over 95% width)
|
||||
:align: "left", "center", or "right" ("center" should be used in general)
|
||||
:alt: Alternative text
|
||||
:figclass: or-image-border (optional, for custom styling)
|
||||
|
||||
This is the caption of the image.
|
||||
|
||||
Images are stored in the :file:`img` directory in the :file:`docs/source` directory. When adding images, please make sure
|
||||
they are in the correct format (PNG, JPEG, or SVG) and that you place them in the correct directory. Use the same directory
|
||||
structure as the rst source file that you want to include the image in. For example, if you want to include an image in
|
||||
:file:`docs/source/user_guide/quick_start.rst`, place the image in :file:`docs/source/img/user_guide/quick_start/`.
|
||||
|
||||
Just for fun, here is an image of my cat:
|
||||
|
||||
.. figure:: /img/dev_guide/contributing_to_the_docs/Oscar.jpeg
|
||||
:width: 50%
|
||||
:align: center
|
||||
:alt: A cute cat
|
||||
:figclass: or-image-border
|
||||
|
||||
This is a picture of my cat, Oscar.
|
||||
|
||||
Hyperlinks
|
||||
----------
|
||||
|
||||
Hyperlinks to external sites are created like this:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
`link text <www.your_url.com>`__
|
||||
|
||||
Replace ``link text`` with the text you want to display as the hyperlink, and ``www.your_url.com`` with the actual URL
|
||||
of the hyperlink. For example: `Hey, I'm a link! <https://www.youtube.com/watch?v=dQw4w9WgXcQ>`__.
|
||||
|
||||
.. warning::
|
||||
|
||||
Always use a double underscore at the end. Don't use a single underscore, as this can cause issues when you have
|
||||
multiple hyperlinks with the same text.
|
||||
|
||||
Admonitions: Tip, Note, Warning, Attention, See also
|
||||
----------------------------------------------------
|
||||
|
||||
As you saw just above, you can add notes and warnings to draw attention to important information. The following are
|
||||
all the possible admonition type: "**attention**", "**caution**", "**danger**", "**error**", "**hint**", "**important**",
|
||||
"**note**", "**tip**", "**warning**". More information can be found
|
||||
`here <https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions>`__.
|
||||
|
||||
The most uses admonitions in the OpenRocket docs are:
|
||||
|
||||
Tip
|
||||
^^^
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. tip::
|
||||
|
||||
This is a tip.
|
||||
|
||||
.. tip::
|
||||
|
||||
This is what the tip looks like.
|
||||
|
||||
Note
|
||||
^^^^
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. note::
|
||||
|
||||
This is a note.
|
||||
|
||||
.. note::
|
||||
|
||||
This is what the note looks like.
|
||||
|
||||
Warning
|
||||
^^^^^^^
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. warning::
|
||||
|
||||
This is a warning.
|
||||
|
||||
.. warning::
|
||||
|
||||
This is what the warning looks like.
|
||||
|
||||
Attention
|
||||
^^^^^^^^^
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. attention::
|
||||
|
||||
This is an attention.
|
||||
|
||||
.. attention::
|
||||
|
||||
This is what a point of attention looks like.
|
||||
|
||||
See Also
|
||||
^^^^^^^^
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. seealso::
|
||||
|
||||
This is a seealso.
|
||||
|
||||
.. seealso::
|
||||
|
||||
See also the following page :doc:`Development Overview </dev_guide/development_overview>`
|
||||
|
||||
Semantic Markup
|
||||
---------------
|
||||
|
||||
Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as \:rolename\:\`content\`.
|
||||
More information can be found `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__. What
|
||||
this means is that you can add roles to pieces of text that have a specific meaning so that Sphinx renders that text
|
||||
in an appropriate way. Below you find some of the most common roles used in the OpenRocket documentation:
|
||||
|
||||
\:menuselection\: Role
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``:menuselection:`` role is used to represent a sequence of menu selections in a user interface.
|
||||
|
||||
Example:
|
||||
:menuselection:`File --> Open example`
|
||||
|
||||
(Ensure you use the correct arrow character, which is ``-->``.)
|
||||
|
||||
\:command\: Role
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``:command:`` role is used to represent a command that a user can enter in a command-line interface.
|
||||
|
||||
Example:
|
||||
To list the contents of a directory, use the :command:`ls` command.
|
||||
|
||||
\:file\: Role
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
The ``:file:`` role is used to indicate a file or a file path.
|
||||
|
||||
Example:
|
||||
Open the configuration file :file:`conf.py` to modify the settings.
|
||||
|
||||
\:kbd\: Role
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The ``:kbd:`` role is used to indicate keyboard keys or shortcuts.
|
||||
|
||||
Example:
|
||||
Press :kbd:`Ctrl` + :kbd:`C` to copy the text.
|
||||
|
||||
\:guilabel\: Role
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``:guilabel:`` role is used to indicate labels of GUI elements like buttons, labels, or fields.
|
||||
|
||||
Example:
|
||||
Click the :guilabel:`Submit` button to save your changes.
|
||||
|
||||
Substitutions
|
||||
-------------
|
||||
|
||||
Sphinx allows you to define substitutions that can be used to replace text in the documentation. This is useful for
|
||||
replacing frequently used text that is prone to update (e.g. versions of something, or dates). More information can be
|
||||
found `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#substitutions>`__.
|
||||
Custom substitutions are defined in :file:`docs/source/conf.py` in the ``rst_prolog`` section. For example, there is a
|
||||
substitution for ``|java_vers|`` that defines the version of Java that OpenRocket requires. You can then use this
|
||||
substitution in the documentation like this: OpenRocket uses Java ``|java_vers|`` (Java |java_vers|).
|
||||
|
||||
Escaping Special Characters
|
||||
---------------------------
|
||||
|
||||
If you need to include a special character in your text that is normally interpreted by Sphinx, you can escape it by
|
||||
preceding it with a backslash. For example, to include a backslash in your text, you would write ``\\``. To include
|
||||
a colon, you would write ``\:``.
|
||||
|
||||
----
|
||||
|
||||
.. note::
|
||||
|
||||
The reStructuredText syntax and Sphinx' capabilities are **very rich**. This page barely scratches the surface of what you can do.
|
||||
Please take the time to read the `documentation on reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__
|
||||
and `Sphinx <https://www.sphinx-doc.org/en/master/usage/index.html>`__. If you find interesting features that you think would be
|
||||
useful for the OpenRocket documentation, please use them and document them here!
|
||||
|
||||
|
||||
Line Wrapping
|
||||
-------------
|
||||
|
||||
Please try to keep your lines in the .rst files under ± 120 characters. This makes it easier to read the documentation in
|
||||
the source files and prevent horizontal scrolling for code blocks. You can break up normal text on a new line without issues,
|
||||
if there is no blank line between two lines of text, the two lines will be rendered as one paragraph in the output.
|
||||
|
||||
Here is an example of correct and incorrect line wrapping inside the source code:
|
||||
|
||||
.. figure:: /img/dev_guide/contributing_to_the_docs/Line-Wrapping.png
|
||||
:width: 80%
|
||||
:align: center
|
||||
:alt: Correct and incorrect line wrapping.
|
||||
:figclass: or-image-border
|
||||
|
||||
Correct and incorrect line wrapping of a .rst file.
|
||||
|
||||
For breaking up list items, you must ensure that the next line is indented by the same amounts of spaces as the first line
|
||||
of the list item. For example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
- This is a list item that is very long and needs to be broken up into multiple lines. This is a list item that is very long and needs to be broken up into multiple lines. This is a list item that is very long and needs to be broken up into multiple lines.
|
||||
|
||||
- This is a list item that is broken up into multiple lines. This is a list item that is broken up into multiple
|
||||
lines. This is a list item that is broken up into multiple lines.
|
||||
|
||||
If you do not have the right indentation, you will get a compile warning when you build the documentation.
|
||||
|
||||
ToDo's
|
||||
------
|
||||
|
||||
If you are working on a part of the documentation that is not yet finished, you can add a ToDo note to remind yourself to
|
||||
finish it later. You can do this by adding a ``todo`` directive to the text. For example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. todo::
|
||||
|
||||
This section is not yet finished. Please come back later to complete it.
|
||||
|
||||
You can view the ToDo's in the documentation if you set the ``todo_include_todos`` option to ``True`` in the
|
||||
:file:`docs/source/conf.py` file. After you've done this and rebuilt the docs, you should see a list of all the ToDo's here:
|
||||
|
||||
.. todolist::
|
||||
12
docs/source/dev_guide/contributing_to_the_website.rst
Normal file
12
docs/source/dev_guide/contributing_to_the_website.rst
Normal file
@ -0,0 +1,12 @@
|
||||
***************************
|
||||
Contributing to the Website
|
||||
***************************
|
||||
|
||||
OpenRocket's website, `openrocket.info <https://openrocket.info/>`__, is hosted on GitHub Pages. The website is built
|
||||
using `Jekyll <https://jekyllrb.com/>`__, a static site generator. The website's source code is located in the
|
||||
`openrocket.github.io <https://github.com/openrocket/openrocket.github.io>`__ repository. The website's content is
|
||||
written in `Markdown <https://daringfireball.net/projects/markdown/>`__ and `HTML <https://html.spec.whatwg.org/multipage/>`__
|
||||
(including CSS and JavaScript).
|
||||
|
||||
Please consult the `README file <https://github.com/openrocket/openrocket.github.io/blob/development/README.md>`__ in the
|
||||
openrocket.github.io repository for instructions on how to contribute to the website.
|
||||
111
docs/source/dev_guide/contributing_to_translations.rst
Normal file
111
docs/source/dev_guide/contributing_to_translations.rst
Normal file
@ -0,0 +1,111 @@
|
||||
****************************
|
||||
Contributing to Translations
|
||||
****************************
|
||||
|
||||
OpenRocket is translated into multiple languages. If you want to help with translations, this document will guide you through the process.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
----
|
||||
|
||||
.. todo::
|
||||
Reference a doc in user_guide for changing the language
|
||||
|
||||
.. todo::
|
||||
Add current state of translations?
|
||||
|
||||
How Translations Work
|
||||
=====================
|
||||
|
||||
OpenRocket's GUI elements do not (*should not*) display hard-coded text. Instead, they use a `Translator <https://github.com/openrocket/openrocket/blob/unstable/core/src/main/java/info/openrocket/core/l10n/Translator.java>`__
|
||||
object with a certain key to look up the text to display. The Translator object is responsible for looking up the text
|
||||
in the appropriate language file and returning the translated text.
|
||||
|
||||
The language files are located in the :file:`core/src/main/resources/l10n` directory. The base file for all translations is
|
||||
``messages.properties``, which contains the English text. Each language has its own file, named ``messages_xx.properties``,
|
||||
where ``xx`` is the language code (e.g. ``messages_nl.properties`` for Dutch). The l10n files are a simple key-value pair
|
||||
where the key is the text to be translated and the value is the translated text. For example, this is a snippet from the
|
||||
``messages.properties`` file:
|
||||
|
||||
.. code-block:: properties
|
||||
|
||||
! RocketPanel
|
||||
RocketPanel.lbl.ViewType = View Type:
|
||||
RocketPanel.lbl.Zoom = Zoom:
|
||||
RocketPanel.lbl.Stability = Stability:
|
||||
|
||||
Comments start with a ``!`` and are ignored. The key is the text to be translated, and the value is the translated text.
|
||||
The key should be unique within the file and should start with the name of the class that uses the text, followed by the type
|
||||
of widget that uses the text, followed by a representation of the text. For example, the key ``RocketPanel.lbl.ViewType``
|
||||
is used by the ``RocketPanel`` class in a label widget to display the text "View Type:". The value for this key is "View Type:".
|
||||
|
||||
Other language files use the exact same keys as the ``messages.properties`` base file, but with the translated text as the value.
|
||||
For example, this is a snippet from the ``messages_nl.properties`` file:
|
||||
|
||||
.. code-block:: properties
|
||||
|
||||
! RocketPanel
|
||||
RocketPanel.lbl.ViewType = Weergavetype:
|
||||
RocketPanel.lbl.Zoom = Zoom:
|
||||
RocketPanel.lbl.Stability = Stabiliteit:
|
||||
|
||||
When you now create a widget in the GUI, you should use the Translator object to get the translated text. For example, to
|
||||
create a label widget with the text "View Type:", you would use the following code:
|
||||
|
||||
.. code-block:: java
|
||||
|
||||
private static final Translator trans = Application.getTranslator();
|
||||
|
||||
JLabel label = new JLabel(trans.get("RocketPanel.lbl.ViewType"));
|
||||
|
||||
When the GUI is displayed, the Translator object will look up the key ``RocketPanel.lbl.ViewType`` in the appropriate language
|
||||
file and return the translated text. If the key is not found in the language file, the Translator object will return the English.
|
||||
This way, the GUI can be easily translated into different languages by simply adding a new language file with the translated text.
|
||||
|
||||
----
|
||||
|
||||
Modifying an Existing Translation
|
||||
=================================
|
||||
|
||||
Open the l10n file for the language you want to modify in the :file:`core/src/main/resources/l10n` directory. For example, to modify
|
||||
the French translation, open the :file:`messages_fr.properties` file, since ``fr`` corresponds to the language code of French.
|
||||
Find the key for the text you want to modify and change the value.
|
||||
|
||||
When you are done, create a pull request with your changes. The maintainers will review your changes and merge them if they are
|
||||
appropriate.
|
||||
|
||||
----
|
||||
|
||||
Creating a New Translation
|
||||
==========================
|
||||
|
||||
If you want to create a new translation for a language that is not yet supported, you can create a new language file in the
|
||||
:file:`core/src/main/resources/l10n` directory. The file should be named ``messages_xx.properties``, where ``xx`` is the language code
|
||||
of the language you want to translate to. For example, to create a translation for Finnish, you would create a file named
|
||||
:file:`messages_fi.properties`.
|
||||
|
||||
Copy the contents of the :file:`messages.properties` file into the new file. Translate the English text into the new language and
|
||||
save the file.
|
||||
|
||||
Edit the :file:`swing/src/main/java/info/openrocket/swing/gui/util/SwingPreferences.java` file and add the new language to the
|
||||
``SUPPORTED_LOCALES`` array. For example, to add Finnish, you would change this line:
|
||||
|
||||
.. code-block:: java
|
||||
|
||||
for (String lang : new String[] { "en", "ar", "de", "es", "fr", "it", "nl", "ru", "cs", "pl", "ja", "pt", "tr" }) {
|
||||
|
||||
To this (notice the addition of ``"fi"`` at the end)
|
||||
|
||||
.. code-block:: java
|
||||
|
||||
for (String lang : new String[] { "en", "ar", "de", "es", "fr", "it", "nl", "ru", "cs", "pl", "ja", "pt", "tr", "fi" }) {
|
||||
|
||||
Finally, add yourself to the list of translation contributors (you deserve some fame! 🙂). This is done in the
|
||||
:file:`swing/src/main/java/info/openrocket/swing/gui/dialogs/AboutDialog.java` file.
|
||||
In this file, edit the String 'CREDITS' and add your details to the list after the 'Translations by:'-tag.
|
||||
|
||||
When you are done, create a pull request with your changes. The maintainers will review your changes and merge them if they are.
|
||||
If you are not at all familiar with git, you can also `create an issue <https://github.com/openrocket/openrocket/issues/new/choose>`__
|
||||
with your changes and the maintainers will create the pull request for you.
|
||||
33
docs/source/dev_guide/development_guidelines.rst
Normal file
33
docs/source/dev_guide/development_guidelines.rst
Normal file
@ -0,0 +1,33 @@
|
||||
**********************
|
||||
Development Guidelines
|
||||
**********************
|
||||
|
||||
In order to maintain a high level of code quality and improve the efficiency for other developers to verify your code,
|
||||
we have established the following guidelines for contributing to the project.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
----
|
||||
|
||||
Coding Standards
|
||||
================
|
||||
|
||||
Where possible, write unit tests for your code (see :doc:`Testing and Debugging </dev_guide/testing_and_debugging>`).
|
||||
This will help to ensure that your code is correct, and will help to prevent regressions in the future.
|
||||
Also include edge cases in your tests.
|
||||
|
||||
Use `atomic commits <https://en.wikipedia.org/wiki/Atomic_commit>`__. Each commit should be a single logical change.
|
||||
Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a
|
||||
feature, it should be split into two separate commits.
|
||||
|
||||
Commit messages should be clear, concise, and useful. The first line should be a short description of the commit, then a blank line,
|
||||
then a more detailed explanation. The commit message should be in the present tense. For example, "Fix bug" and not "Fixed bug".
|
||||
|
||||
If applicable, include a reference to the issue that the commit addresses. For example, if you're working on a fix for GitHub
|
||||
issue #123, then format your commit message like this: "[#123] Fix bug". This makes it easier to track which commits are
|
||||
associated with which issues.
|
||||
|
||||
Pull Request Process
|
||||
====================
|
||||
74
docs/source/dev_guide/development_overview.rst
Normal file
74
docs/source/dev_guide/development_overview.rst
Normal file
@ -0,0 +1,74 @@
|
||||
********************
|
||||
Development Overview
|
||||
********************
|
||||
|
||||
Welcome to the OpenRocket Development Guide! This documentation is designed for developers interested in contributing to OpenRocket.
|
||||
|
||||
This guide covers the architecture, codebase, and development workflows in detail. To dive deeper into specific topics,
|
||||
use the links below to navigate to different sections of this development guide. To learn more about the technical aspects
|
||||
of OpenRocket, such as the aerodynamic calculations, refer to the `Technical documentation <https://openrocket.info/documentation.html>`__.
|
||||
|
||||
Code structure
|
||||
==============
|
||||
|
||||
OpenRocket is a Java application organized using the Java Platform Module System (JPMS) and built with `Gradle <https://gradle.org/>`__.
|
||||
The code is organized in the following two packages:
|
||||
|
||||
- `info.openrocket.core <https://github.com/openrocket/openrocket/tree/unstable/core>`__ - The backend of OpenRocket. \
|
||||
This package contains the classes that represent the rocket and its components, as well as the simulation engine. \
|
||||
The classes in this package are not dependent on any GUI libraries and can be used in other applications.
|
||||
|
||||
- `info.openrocket.swing <https://github.com/openrocket/openrocket/tree/unstable/swing>`__ - The GUI of OpenRocket. \
|
||||
This package contains the classes that create the user interface. OpenRocket uses the Java Swing library for the GUI.
|
||||
|
||||
Further Reading
|
||||
===============
|
||||
|
||||
Explore the following sections to learn more about OpenRocket's development:
|
||||
|
||||
- :doc:`Development Environment Setup </dev_guide/development_setup>`
|
||||
|br_no_pad|
|
||||
*How to set up your development environment to build and run OpenRocket.*
|
||||
|
||||
- :doc:`OpenRocket Architecture </dev_guide/architecture>`
|
||||
|br_no_pad|
|
||||
*An overview of the high-level code architecture of OpenRocket.*
|
||||
|
||||
- :doc:`Codebase Walkthrough </dev_guide/codebase_walkthrough>`
|
||||
|br_no_pad|
|
||||
*A detailed guide to the codebase of OpenRocket.*
|
||||
|
||||
- :doc:`Development Guidelines </dev_guide/development_guidelines>`
|
||||
|br_no_pad|
|
||||
*Guidelines for contributing to OpenRocket.*
|
||||
|
||||
- :doc:`Testing and Debugging </dev_guide/testing_and_debugging>`
|
||||
|br_no_pad|
|
||||
*How to test and debug the OpenRocket code.*
|
||||
|
||||
- :doc:`API Documentation </dev_guide/api_documentation>`
|
||||
|br_no_pad|
|
||||
*Documentation for the OpenRocket API.*
|
||||
|
||||
- :doc:`Building and Releasing </dev_guide/building_releasing>`
|
||||
|br_no_pad|
|
||||
*How to build and release new OpenRocket versions.*
|
||||
|
||||
- :doc:`Contributing to the Website </dev_guide/contributing_to_the_website>`
|
||||
|br_no_pad|
|
||||
*How to contribute to the* `openrocket.info <https://openrocket.info/>`__ *website.*
|
||||
|
||||
- :doc:`Contributing to Translations </dev_guide/contributing_to_translations>`
|
||||
|br_no_pad|
|
||||
*How to contribute to translating the OpenRocket UI into different languages.*
|
||||
|
||||
- :doc:`Contributing to the Documentation </dev_guide/contributing_to_the_docs>`
|
||||
|br_no_pad|
|
||||
*How to contribute to this OpenRocket documentation.*
|
||||
|
||||
- :doc:`FAQ and Troubleshooting </dev_guide/faq_troubleshooting>`
|
||||
|br_no_pad|
|
||||
*Frequently asked questions and troubleshooting tips for developers.*
|
||||
|
||||
**We encourage contributions from everyone and hope this guide helps you get started with developing OpenRocket. ❤️**
|
||||
|
||||
243
docs/source/dev_guide/development_setup.rst
Normal file
243
docs/source/dev_guide/development_setup.rst
Normal file
@ -0,0 +1,243 @@
|
||||
*****************************
|
||||
Development Environment Setup
|
||||
*****************************
|
||||
|
||||
This guide will walk you through setting up the development environment to build OpenRocket from the source code.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
----
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
- `JDK 17 <https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html>`__. OpenRocket is developed using Java 17,
|
||||
so you will need to install it to build and run OpenRocket. If you have multiple versions of Java installed, ensure that
|
||||
Java |java_vers| is the default version.
|
||||
|
||||
- `Git <https://git-scm.com/downloads>`__. Git is a version control system that is used to manage the source code for OpenRocket.
|
||||
You will need to install Git to clone the OpenRocket repository.
|
||||
|
||||
- `GitHub Account <https://github.com>`__. GitHub is a platform for hosting Git repositories. You will need a GitHub account to
|
||||
fork the OpenRocket repository and submit pull requests.
|
||||
|
||||
- `Gradle <https://gradle.org/install/>`__. OpenRocket uses Gradle as its build system. You will need to install Gradle to build OpenRocket.
|
||||
|
||||
Obtaining the Source Code
|
||||
=========================
|
||||
|
||||
The source code for OpenRocket is hosted on `GitHub <https://github.com/openrocket/openrocket>`__. However, you cannot change
|
||||
this code directly. This is because the OpenRocket repository is the official repository for the project, and only the project
|
||||
maintainers can make changes to it. This is to ensure that the codebase remains stable and consistent.
|
||||
Instead, you must fork the OpenRocket repository, which creates a personal copy of the repository that you can make changes to.
|
||||
You can then submit a pull request to the OpenRocket repository to propose your changes.
|
||||
|
||||
Forking the Repository
|
||||
----------------------
|
||||
|
||||
The first step is to fork the OpenRocket repository. As mentioned earlier, the OpenRocket repository is the official repository
|
||||
for the project, and only the project maintainers can make changes to it.
|
||||
|
||||
Go to the OpenRocket repository on GitHub (`link <https://github.com/openrocket/openrocket>`__) and click the :guilabel:`Fork` button:
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/fork_repo.png
|
||||
:align: center
|
||||
:width: 90%
|
||||
:alt: Forking the official OpenRocket repository.
|
||||
|
||||
Forking the official OpenRocket repository on `github.com/openrocket/openrocket <https://github.com/openrocket/openrocket>`__.
|
||||
|
||||
You can leave the default settings and click ``Create fork``. This will create a copy of the OpenRocket repository in your GitHub account:
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/forked_repo.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Your forked repo.
|
||||
|
||||
Your forked repo.
|
||||
|
||||
You can always retrieve your forked repository under your GitHub account, under ``Your repositories``, or by visiting the URL
|
||||
``https://github.com/<your_username>/openrocket`` (replace ``<your_username>``
|
||||
with your actual username).
|
||||
|
||||
Cloning the Repository
|
||||
----------------------
|
||||
|
||||
Now that you have forked the OpenRocket repository, you can clone it to your local machine. To do this, open a terminal
|
||||
and run the following command (replace ``[YOUR USERNAME]`` with your GitHub username):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Use the following command if you have set up SSH keys with GitHub
|
||||
git clone git@github.com:[YOUR USERNAME]/openrocket.git
|
||||
|
||||
# Otherwise, clone the repository using HTTPS
|
||||
git clone https://github.com/[YOUR USERNAME]/openrocket.git
|
||||
|
||||
This will clone the OpenRocket repository to your local machine. You can now make changes to the code and push them to your forked repository.
|
||||
|
||||
One final step you need to do is to initialize the submodules. OpenRocket uses submodules for some of its dependencies.
|
||||
To initialize the submodules, run the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git submodule init
|
||||
git submodule update
|
||||
|
||||
|
||||
Keeping your Fork in Sync
|
||||
-------------------------
|
||||
|
||||
Once you have forked the OpenRocket repository, you will need to keep your fork in sync with the official repository. This is because
|
||||
the official repository may have changes that are not in your fork, and you will want to keep your fork up-to-date with the latest changes.
|
||||
For example, in the following image you can see that your fork is 10 commits behind the official repository:
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/forked_repo_outdated.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: An outdated forked repo.
|
||||
|
||||
An outdated forked repo.
|
||||
|
||||
Luckily, GitHub makes it easy to keep your fork in sync with the official repository. You can do this by clicking the
|
||||
``Sync fork`` button on your forked repository page and then clicking the :guilabel:`Update branch` button:
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/sync_fork.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Syncing your forked repo on GitHub.
|
||||
|
||||
Syncing your forked repo on GitHub.
|
||||
|
||||
If all went well, your fork should now be up-to-date with the official repository:
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/forked_repo_up_to_date.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: An up-to-date forked repo.
|
||||
|
||||
An up-to-date forked repo.
|
||||
|
||||
.. warning::
|
||||
It is important to keep your fork in sync with the official repository. If you don't, you may encounter conflicts
|
||||
when you try to submit a pull request.
|
||||
|
||||
**Regularly check your forked repository to see if it is behind the official repository**. If it is, sync your fork!
|
||||
|
||||
Now you have updated your fork, but you still need to update your local repository (your clone).
|
||||
To do this, you need to fetch the changes from the official repository and pull them into your local repository.
|
||||
You can do this by running the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git fetch && git pull
|
||||
|
||||
Setting Up the Development Environment
|
||||
======================================
|
||||
|
||||
This section will guide you through setting up the development environment to build OpenRocket from the source code.
|
||||
|
||||
IntelliJ IDEA
|
||||
-------------
|
||||
|
||||
`IntelliJ IDEA <https://www.jetbrains.com/idea/>`__ is a popular Java IDE that is used by many developers. It has a lot of
|
||||
features that make it easier to develop Java applications. We **highly** recommend using IntelliJ IDEA for developing
|
||||
OpenRocket. You can download the Community Edition for free from the `JetBrains website <https://www.jetbrains.com/idea/download>`__
|
||||
(scroll down to “IntelliJ IDEA Community Edition” and click the download button).
|
||||
|
||||
Once you have downloaded and installed IntelliJ IDEA, you can open the OpenRocket project:
|
||||
|
||||
1. **Open IntelliJ IDEA**
|
||||
Start IntelliJ IDEA and select "Open" (Go to :menuselection:`File --> Open`).
|
||||
|
||||
2. **Select the OpenRocket project**
|
||||
Navigate to the directory where you cloned OpenRocket and select the project.
|
||||
|
||||
3. **Import Project as Gradle Project**
|
||||
IntelliJ should automatically detect that this is a Gradle project. If prompted, select ``Load Gradle Project``.
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/load_gradle_project.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Load Gradle Project.
|
||||
|
||||
IntelliJ IDEA will automatically detect that this is a Gradle project and prompt you to load it. Click ``Load Gradle Project``.
|
||||
|
||||
4. **Configure JDK for the Project**
|
||||
- Go to :menuselection:`File --> Project Structure --> (Project Settings -->) Project`.
|
||||
- Set the Project SDK to JDK |java_vers|.
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/project_sdk.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Set the project SDK.
|
||||
|
||||
Set the project SDK to JDK |java_vers|.
|
||||
|
||||
If JDK |java_vers| is not listed, you can download it from the Project Structure dialog by \
|
||||
going to :menuselection:`(Platform Settings -->) SDKs`, clicking the :guilabel:`+` button, and selecting ``Download JDK...``. Then select \
|
||||
version |java_vers| and any vendor (e.g. OpenJDK, Amazon Corretto, ...).
|
||||
|
||||
- Confirm in the Project Structure dialog under :menuselection:`(Project Settings -->) Modules` that the SDK in each module is set to JDK |java_vers|. \
|
||||
If not, you can change it by selecting the module and setting the SDK in the right pane. Ensure that the list view on the bottom-right \
|
||||
does not show ``<No SDK>``. If it does, click the *Module SDK* dropdown and click (again) on the JDK |java_vers| SDK.
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/modules_sdk.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Set the module SDK.
|
||||
|
||||
Set the module SDK to JDK |java_vers|.
|
||||
|
||||
5. **Run the Application**
|
||||
By default, IntelliJ should be set up with 3 run configurations:
|
||||
|
||||
- ``SwingStartup``: Run the application directly from within IntelliJ. You will user this configuration most of the time. \
|
||||
You can also run IntelliJ in debug mode by clicking the green bug icon next to the play button.
|
||||
|
||||
- ``openrocket-jar``: Run all the unit tests and build the application as a JAR file.
|
||||
|
||||
- ``openrocket-test``: Only run the unit tests.
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/run_configurations.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Default installed run configurations.
|
||||
|
||||
The default installed run configurations.
|
||||
|
||||
You can run the application by selecting the ``SwingStartup`` configuration and clicking the green play button.
|
||||
This will instantiate the OpenRocket application from within IntelliJ IDEA. If you want to stop the running application,
|
||||
click the red square button on the top-right in IntelliJ.
|
||||
|
||||
.. figure:: /img/dev_guide/development_setup/swingstartup.png
|
||||
:align: center
|
||||
:width: 80%
|
||||
:alt: Running OpenRocket from IntelliJ IDEA.
|
||||
|
||||
Running OpenRocket directly from IntelliJ IDEA.
|
||||
|
||||
6. **That's it!** You can now start developing OpenRocket. 🚀
|
||||
|
||||
Command Line Interface
|
||||
----------------------
|
||||
|
||||
It is also possible to develop in a text editor and build OpenRocket from the command line using Gradle. Please refer to the :doc:`Building and Releasing </dev_guide/building_releasing>`
|
||||
section for all the possible Gradle tasks. To run OpenRocket, you can use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
./gradlew run
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
1. **JDK Not Recognized**
|
||||
Ensure that the JDK path is correctly configured in :menuselection:`File --> Project Structure --> SDKs`.
|
||||
|
||||
2. **Gradle Sync Issues**
|
||||
- If IntelliJ fails to import Gradle projects correctly, try refreshing the Gradle project by clicking on the "Reload All Gradle Projects" icon in the Gradle tool window.
|
||||
- Ensure the `gradle-wrapper.properties` file points to the correct Gradle version which supports Java |java_vers|.
|
||||
|
||||
16
docs/source/dev_guide/faq_troubleshooting.rst
Normal file
16
docs/source/dev_guide/faq_troubleshooting.rst
Normal file
@ -0,0 +1,16 @@
|
||||
***********************
|
||||
FAQ and Troubleshooting
|
||||
***********************
|
||||
|
||||
.. rubric:: Q: Why does OpenRocket still use the "ancient" Java language? Python and web-based programs are the future.
|
||||
|
||||
A: Java is a very powerful language and is still widely used in the industry. While it is true that Java is not as popular
|
||||
with (new) developers as Python or web-based languages, there are currently no plans of rewriting the codebase in another
|
||||
language. The main reason for this is that it would take a lot of time to rewrite the codebase, more time than the current
|
||||
OpenRocket developers can afford to miss of their (limited) spare time. Besides, the current Java codebase is
|
||||
still working fine and has been tested by many users over the years.
|
||||
|
||||
That being said, maintaining a Java application does have challenges, mainly in ensuring it runs on all platforms and
|
||||
hardware configurations. Maintaining the GUI and 3D view has proven to be very challenging. Additionally, Java cannot be
|
||||
run on mobile devices such as iOS devices. If you are a developer and would like to contribute to the codebase rewrite,
|
||||
please contact the OpenRocket developers to see what you could do to help!
|
||||
11
docs/source/dev_guide/testing_and_debugging.rst
Normal file
11
docs/source/dev_guide/testing_and_debugging.rst
Normal file
@ -0,0 +1,11 @@
|
||||
*********************
|
||||
Testing and Debugging
|
||||
*********************
|
||||
|
||||
Unit Testing
|
||||
============
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
IDE debugger, print statements, in-program debug log, debug command line argument...
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 683 KiB |
BIN
docs/source/img/dev_guide/building_releasing/install4j_build.png
Normal file
BIN
docs/source/img/dev_guide/building_releasing/install4j_build.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 265 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 188 KiB |
BIN
docs/source/img/dev_guide/contributing_to_the_docs/Oscar.jpeg
Normal file
BIN
docs/source/img/dev_guide/contributing_to_the_docs/Oscar.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 382 KiB |
BIN
docs/source/img/dev_guide/development_setup/fork_repo.png
Normal file
BIN
docs/source/img/dev_guide/development_setup/fork_repo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 437 KiB |
BIN
docs/source/img/dev_guide/development_setup/forked_repo.png
Normal file
BIN
docs/source/img/dev_guide/development_setup/forked_repo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 585 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 554 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 557 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 326 KiB |
BIN
docs/source/img/dev_guide/development_setup/modules_sdk.png
Normal file
BIN
docs/source/img/dev_guide/development_setup/modules_sdk.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 184 KiB |
BIN
docs/source/img/dev_guide/development_setup/project_sdk.png
Normal file
BIN
docs/source/img/dev_guide/development_setup/project_sdk.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 162 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 333 KiB |
BIN
docs/source/img/dev_guide/development_setup/swingstartup.png
Normal file
BIN
docs/source/img/dev_guide/development_setup/swingstartup.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 580 KiB |
BIN
docs/source/img/dev_guide/development_setup/sync_fork.png
Normal file
BIN
docs/source/img/dev_guide/development_setup/sync_fork.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 965 KiB |
BIN
docs/source/img/openrocket_logo_256.png
Normal file
BIN
docs/source/img/openrocket_logo_256.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
BIN
docs/source/img/setup/getting_started/02.04.01.File_Menu.png
Normal file
BIN
docs/source/img/setup/getting_started/02.04.01.File_Menu.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 119 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 194 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 114 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 121 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 80 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 198 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 130 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 131 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 169 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 126 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 138 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 129 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 164 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 149 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 165 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 593 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 166 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 551 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 103 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
BIN
docs/source/img/setup/getting_started/2023.01.Open_Example.png
Normal file
BIN
docs/source/img/setup/getting_started/2023.01.Open_Example.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 146 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
BIN
docs/source/img/setup/installation/about_dialog.png
Normal file
BIN
docs/source/img/setup/installation/about_dialog.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user