Merge pull request #25 from RocketPy-Team/doc/improve-readme

DOC: Improve README

Author: Gui-FernandesBR

.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,33 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+
+name: Publish New Version to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.9"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -1,22 +1,43 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/LogoWhiteonTransparentBG-ByRocketeersForRocketeers.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/LogoBlackonTransparentBG-ByRocketeersForRocketeers.png">
+  <img alt="RocketPy Logo" src="https://raw.githubusercontent.com/RocketPy-Team/RocketPy/master/docs/static/RocketPy_Logo_black.png">
+</picture>
+
+<br>
+
+[![Documentation Status](https://readthedocs.org/projects/rocketpyalpha/badge/?version=latest)](https://docs.rocketpy.org/en/latest/?badge=latest)
+[![Chat on Discord](https://img.shields.io/discord/765037887016140840?logo=discord)](https://discord.gg/b6xYnNh)
+[![Sponsor RocketPy](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/RocketPy-Team)
+[![Instagram](https://img.shields.io/badge/Instagram-E4405F?style=flat&logo=instagram&logoColor=white)](https://www.instagram.com/rocketpyteam)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=flat&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/rocketpy)
+
+<br>
+
 # Rocket Serializer
 
-Rocket Serializer is a Python library that provides serialization capabilities
-for OpenRocket files. It allows you to read OpenRocket files using a simple and
-intuitive command line interface.
+`rocketserializer` is a Python library that provides serialization capabilities
+for OpenRocket files. It allows you to read OpenRocket files (.ork) using a
+simple and intuitive command line interface. After serializing the file, you
+can use the data to create your RocketPy simulation.
+
+## Example
+
+<img src="./static/demo_2.gif" width="100%" />
 
 ## Installation
 
-You can install Rocket Serializer using pip:
+You can install `rocketserializer` using pip:
 
 ```shell
-pip install rocket-serializer
+pip install rocketserializer
 ```
 
 ## Requirements
 
 ### Java
 
-You need Java to be installed on your system to use Rocket Serializer.
+You need Java to be installed on your system to use `rocketserializer`.
 We recommend downloading Java 17, which is required to run OpenRocket-23.09.
 
 https://www.oracle.com/java/technologies/downloads/
@@ -33,77 +54,89 @@ correct java version to run the jar file.
 
 ### Python Packages
 
-Once you download the package `rocket-serializer`, the following dependencies
+Once you download the `rocketserializer` package, the following dependencies
 will be automatically installed:
 
 - bs4
-- click
+- click>=8.0.0
 - lxml
 - numpy
-- orhelper
+- orhelper==0.1.3
 - pyyaml
-- rocketpy
-- nbformat
+- rocketpy>=1.1.0
+- nbformat>=5.2.0
 
 ## Usage - command line interface
 
-To use Rocket Serializer, you just need to use the cli option of the library.
-Here's an example:
+The `rocketserializer` package will automatically install 2 command-line-interface (cli)
+options, here's an example:
+
+### Serialization
+
+To create a `parameters.json` file from an OpenRocket file, use the following command:
+
+```bash
+ork2json --filepath your_rocket.ork
+```
+
+Or, for a more verbose output, you can use the following command:
 
 ```bash
-rocket-serializer ork2json --filepath path/to/input.ork --output path/to/output
+ork2json --filepath your_rocket.ork --verbose True
 ```
 
 The options are the following:
 
 - `--filepath`: The .ork file to be serialized.
-- `--output` : Path to the output folder. If not set, the output will be saved in the same folder os the filepath.
-- `--eng` : Path to the engine file. If not set, the library will get the thrust curve from the OpenRocket file.
+- `--output` : Path to the output folder. If not set, the output will be saved in the same folder as the `filepath`.
 - `--ork_jar` : Specify the path to the OpenRocket jar file. If not set, the library will try to find the jar file in the current directory.
+- `--encoding` : The encoding of the .ork file. By default, it is set to `utf-8`.
 - `--verbose` : If you want to see the progress of the serialization, set this option to True. By default, it is set to False.
 
+Only  the `--filepath` option is mandatory.
+
+### Creating a simulation notebook
+
+```bash
+ork2notebook --filepath your_rocket.ork
+```
+
+The options are pretty much the same as the serialization command!
+
 ### Limitations
 
 This code won't work for your rocket if it has any of the following features:
 
-- Your file wasn't saved in English
-- Your file doesn't contain simulation data
-- Your rocket has more than one stage
-- Your rocket has more than one engine
-- Your rocket has more than one nosecone
+- Your .ork file must be saved in English
+- Your .ork file must be saved with at least 1 simulation data
+- Only one single stage is supported
+- Only a single motor is supported
+- Only a single nose cone is supported
 
-### Deserialization
+## Roadmap
 
-Still to be done.
+- 2024 June : First public release, start receiving feedback from the community.
 
-## License
-
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+Before the first public release, we will listen to the community's feedback before defining the roadmap for the next releases.
 
 ## Contact
 
-For any inquiries or feedback, please email us at [rocketpyteam@gmail.com](mailto:rocketpyteam@gmail.com).
 If you find any bug or if you want to request new features, please open an issue
 on GitHub.
-
-## Contributors
-
-This project is maintained by the RocketPy Team, a group of students and
-software developers from all over the world.. The main contributors to this
-project are:
-
-- Patrick Sampaio Brandão
-- Franz Masatoshi Yuri
-- Guilherme Fernandes Alves
+In case you don't have a GitHub account, you can reach out to us on RocketPy's
+Discord server.
 
 ## How to Contribute
 
 The 3 main ways of contributing to this project are:
 
-1. Reporting bugs and suggesting new features by opening issues on GitHub.
-2. Submitting .ork files that can be used to test the library.
-3. Developing new features and fixing bugs by opening pull requests on GitHub.
-
-## More Information
-
-For more information, please visit the [RocketPy Team GitHub repository](https://github.com/RocketPy-Team/OpenRocketSerializer).
+1. **Reporting bugs and suggesting new features.**
+    - Use GitHub, preferably, to report bugs and suggest new features.
+    - In case you don't have a GitHub account, you can reach out to us on RocketPy's Discord server
+2. **Sharing .ork files that can be used to test the library.**
+    - If you have a .ork file that is not working with the library, please share it with us.
+    - If you have a .ork file that is working with the library, please share it with us.
+    - If you allow us to use and share your .ork file, we can add it to the test suite.
+3. **Developing new features and fixing bugs thorough pull requests on GitHub.**
+    - If you want to develop new features, you are more than welcome to do so.
+    - Please reach out to the maintainers to discuss the new feature before starting the development. 

rocketserializer/cli.py

@@ -211,7 +211,8 @@ def ork2notebook(filepath, output, ork_jar=None, encoding="utf-8", verbose=False
     the .ipynb file.
     """
     if not output:
-        output = os.path.dirname(filepath)
+        filepath = Path(filepath)
+        output = filepath.parent
         logger.warning(
             "[ork2notebook] Output folder not specified. Using '%s' instead.",
             Path(output).as_posix(),