docs: create tutorials

MadeInPierre · Jun 6, 2023 · 93780d2 · 93780d2
1 parent 96ba022
commit 93780d2
Show file tree

Hide file tree

Showing 23 changed files with 671 additions and 83 deletions.
diff --git a/.gitignore b/.gitignore
@@ -89,6 +89,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/apidocs/
 
 # PyBuilder
 .pybuilder/

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -20,7 +20,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-merge-conflict
-      - id: check-docstring-first
+      # - id: check-docstring-first
       - id: check-shebang-scripts-are-executable
       - id: check-added-large-files # TODO add many others!
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,6 @@
+Build the documentation and serve it locally on https://127.0.0.1:8000 using:
+
+```bash
+pip install sphinx-autobuild myst-parser sphinx-rtd-theme sphinx-autodoc2
+sphinx-autobuild docs docs/_build/html
+```
diff --git a/docs/_static/screenshot_full.png b/docs/_static/screenshot_full.png
diff --git a/docs/index.md b/docs/index.md
@@ -5,11 +5,21 @@
 :hidden:
 :maxdepth: 3
 
-tutorials/installation
-tutorials/getting_started
-tutorials/customization
+quickstart/installation
+quickstart/getting_started
+tutorials/tutorials
+quickstart/customization
 ```
 
+<!-- ```{toctree}
+:caption: '📙 Tutorials'
+:hidden:
+:maxdepth: 3
+
+tutorials/1_config_structure
+tutorials/2_define_portfolio
+``` -->
+
 ```{toctree}
 :caption: '📚 API Reference'
 :hidden:

diff --git a/docs/tutorials/customization.md → docs/quickstart/customization.md b/docs/tutorials/customization.md → docs/quickstart/customization.md
@@ -4,44 +4,27 @@
 There are three ways to configure options in Finalynx:
 
 A. **From the `Assistant` class:**
-```py
-Assistant(option1=value1, ...)
+```python
+portfolio = Portfolio(...)  # <- your config
+Assistant(portfolio, option1=value1, ...).run()
 ```
 B. **From a custom Python script:**
-```sh
+```bash
 python your_config.py [options]
 ```
 C. **From Finalynx's standalone mode:**
-```sh
+```bash
 python -m finalynx --json=your_config.json [options]
 ```
 
-See the full list of available options below:
-```md
-Usage:
-  finalynx [--json=input-file] [--format=string] [dashboard] [options]
-  finalynx (-h | --help)
-  finalynx (-v | --version)
-
-Options:
-  -h --help            Show this help message and exit
-  -v --version         Display the current version and exit
-
-  # Only valid when calling `python -m finalynx`
-  --json=input-file    When calling Finalynx in standalone mode, JSON file is mandatory
-
-  --format=string      Customize the output format to your own style and information
-
-  -i --ignore-orphans  Ignore fetched lines that you didn't reference in your portfolio
-  -c --clear-cache     Delete any data from Finary that was cached locally
-  -f --force-signin    Clear cache, cookies and credentials files to sign in again
-  -a --hide-amounts    Display your portfolio with dots instead of the real values
-  -r --hide-root       Display your portfolio without the root (cosmetic preference)
+See the full list of available options by running:
+```bash
+python your_config.py --help
 ```
 
 ## 🌈 Output format
 It is possible to specify a custom print format to customize the look of your tree:
-```sh
+```bash
 python your_config.py --format="your format"                 # shell
 python -m finalynx --json=input.json --format="your format"  # shell
 Assistant(output_format="your format", other_arguments...)   # python
@@ -64,7 +47,7 @@ Assistant(output_format="your format", other_arguments...)   # python
 ```
 
 Here are some examples of valid formats:
-```sh
+```bash
 python your_config.py --format="[console]"  # Default, prints the full colored tree
 python your_config.py --format="[text]"  # Print the full tree but colorless
 python your_config.py --format="[blue][amount] [name][/]"  # Use [/] to reset the color
@@ -99,3 +82,36 @@ class Node(Render):
         return self.target.render(format)
 ```
 </details>
+
+## ⛓ Sidecars
+
+What if you could show additional information along with your main tree with columns on the right that show customizable information, like ideal investment amounts, expected yearly performance, delta investments, and so on?
+
+![full screenshot](https://github.com/MadeInPierre/finalynx/blob/main/docs/_static/screenshot.png)
+
+Meet _sidecars_: each sidecar is a column on the right of the main tree that displays any information about the node on the same console line. It uses the same output format structure defined above.
+
+A sidecar is defined by 4 parameters:
+- **Output format:** Specify what you want to render in this column (aka. sidecar). This uses the same format as the "output format" explained above, except it will be rendered in a separate column on the right of the tree.
+- **Condition format:** Specify any output format. Only show the output format for each node it this render returns a non-empty string. This is useful to make multiple sidecars work together (e.g. only show ideal amounts if the node requires a non-zero delta transaction).
+- **Title:** customize the column (aka. sidecar) title. By default, a title is generated from the output format.
+- **Show folders:** A boolean to choose if you want to only show elements for `Line` objects and not `Folder` objects. When set to `False`, only expanded folders will not have any information displayed.
+
+Define your own sidecars using one of two options:
+1. From your Python configuration:
+
+```python
+assistant = Assistant(
+    portfolio,
+    sidecars=[
+        Sidecar("[ideal]", ["delta"], "HELLO", False),
+        Sidecar("[delta]", show_folders=False),
+    ],
+).run()
+```
+
+1. From the command line (comma-separated values):
+
+```bash
+python your_config.py --sidecar="[ideal],[delta],HELLO,False" --sidecar="[delta],,,False"
+```
diff --git a/docs/tutorials/getting_started.md → docs/quickstart/getting_started.md b/docs/tutorials/getting_started.md → docs/quickstart/getting_started.md
diff --git a/docs/quickstart/installation.md b/docs/quickstart/installation.md
@@ -0,0 +1,55 @@
+# 🔧 Installation
+
+## Quick start
+
+If you don't plan on touching the code, simply run (with python >=3.10 and pip installed):
+```sh
+pip install finalynx  # run again with --upgrade to update
+```
+
+And you're done! Now create your own copy of the [`demo.py`](https://github.com/MadeInPierre/finalynx/blob/main/examples/demo.py) example anywhere and run it to make sure everything works. You can now customize it for your own needs 🚀
+
+```{tip}
+**Pro Tip 💡:** Why not setup a script to autorun your config in a new terminal on startup? Could be a nice view 🤭
+```
+
+```{note}
+**Want to help this project grow?** Checkout the [**contribution guidelines**](https://finalynx.readthedocs.io/en/latest/project/contributing.html) to learn how to install this project in
+development mode 🧑‍💻
+```
+
+## Detailed instructions
+
+If you need a bit more details, here is a summary of all commands to need to run to make Finalynx work with a basic configuration. First, make sure you have a recent Python version (must be 3.10 or above) by running:
+
+```bash
+python3 --version  # Must be >=3.10
+```
+
+```{note}
+**Note:** If you have any questions or difficulty, please [**open an issue**](https://github.com/MadeInPierre/finalynx/issues/new), we'll be happy to help, teach and learn together! No matter the level, there are no dumb questions right? 🤝
+```
+
+There are two options to install Finalynx:
+
+1. Install using `pip`, and paste the contents of the `demo.py` example file in any folder (e.g. Documents):
+```bash
+pip3 install finalynx        # Automatically install finalynx globally, lets you use `from finalynx import *`
+cd somewhere/like/Documents  # Make sure you use any folder outside system files, like your home directory
+touch assistant_config.py    # Create your configuration file and past the contents of the `demo.py` example
+python3 assistant_config.py  # Run your configuration file to make sure everything works, then customize it!
+```
+
+1. Install using `git clone`, lets you modify the code yourself, contribute to this project, and get the latest code to avoid waiting for new releases:
+```bash
+cd somewhere/like/Documents/  # Choose any folder to download Finalynx's code, must be outside of system folders
+git clone https://github.com/MadeInPierre/finalynx.git  # Download the code as a git repository (easy to update)
+cd finalynx  # Go inside the newly downloaded project
+pip3 install poetry && poetry check && poetry install  # Install all project dependencies
+pip3 install -e .  # Install the code globally, -e means you can change the code without the need to reinstall
+python3 examples/demo.py  # Try out the demo example to make sure everything works
+
+cp examples/demo.py assistant_config.py  # Create your own copy of the demo, this will be your personal config
+# Customize your config now to create your own portfolio!
+python3 assistant_config.py --help  # Run your own config (use --help to see customizable options)
+```
diff --git a/docs/tutorials/installation.md b/docs/tutorials/installation.md
diff --git a/docs/tutorials/tutorials.md b/docs/tutorials/tutorials.md
@@ -0,0 +1,7 @@
+# 📖 Tutorials
+
+Looking for a step-by-step guide to understand each concept available in Finalynx? Have a look a the [`examples/tutorials` folder in the Github repository](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials)! It contains incremental instructions on how to build your own portfolio configuration and use Finalynx with is customizable options.
+
+```{note}
+**Note:** Want to also have some additional explanation on this documentation website? Please [open an issue](https://github.com/MadeInPierre/finalynx/issues/new) to show your interest and motivate the author to write them 🙃
+```
diff --git a/examples/demo.py b/examples/demo.py
@@ -1,20 +1,32 @@
 #!/usr/bin/env python
 """
+Welcome to Finalynx!
+
 Finalynx is a tool to organize your investments in a custom hierarchy,
-fetch real-time values using the Finary API, set targets, and simulate your
-portfolio evolution with optional life events and portfolio operations.
+fetch real-time investment values from your personal account using the
+Finary API and other pre-built sources, set targets, and simulate your
+portfolio evolution with optional life events. Finalynx then outputs a
+list of transfers between investments as recommendations to reach your
+life goals. Finalynx is available as a CLI tool and as a web dashboard.
+
+Finalynx is not a financial advisor and does not give financial advice.
+Use this tool to help you make your own decisions. With that said, have
+fun! Contributions and feedback on GitHub are warmly welcome!
 
-This module is maintained by MadeInPierre.
-You can always get the latest version of this module at:
+This module is maintained by MadeInPierre. You can always get the latest
+version of this module at:
 > https://github.com/madeinpierre/finalynx
+
+Checkout the documentation and tutorials at:
+> https://finalynx.readthedocs.io
 """
 # noreorder
+from datetime import date
 from rich import inspect, print, pretty, traceback  # noqa
 from finalynx import TargetRange, TargetMin, TargetMax, TargetRatio, TargetGlobalRatio  # noqa
 from finalynx import Folder, Line, Bucket, SharedFolder, Portfolio, FolderDisplay  # noqa
-from finalynx import AssetClass, AssetSubclass  # noqa
-from finalynx import Copilot, Simulator
-from finalynx import Assistant
+from finalynx import AssetClass, AssetSubclass, Envelope, PEA, AV, PER  # noqa
+from finalynx import Copilot, Simulator, Assistant
 
 # Enable rich's features
 traceback.install()
@@ -35,10 +47,18 @@
         ],
     )
 
+    """
+    Define your Envelopes, which are your investment accounts. They can
+    be used to store cash, or to store other investments. They can also
+    be used to store your debts.
+    """
+    my_bank = Envelope("Bank", "BAN", date_created=date(2023, 1, 1), key="NAME_IN_FINARY")
+    my_av = AV("Linxea Spirit 2", "LIX", date_created=date(2018, 7, 1), key="NAME_IN_FINARY")
+
     """
     Define your complete portfolio structure with Lines, Folders (groups
-    of Lines), and SharedFolders (Folder with one Bucket). See the
-    README file or the documentation for complete usage instructions.
+    of Lines), and SharedFolders (Folder with one Bucket). See the README
+    file or the online documentation for complete usage instructions.
     """
     portfolio = Portfolio(
         "Portfolio",
@@ -51,24 +71,15 @@
                         "Daily",
                         target=TargetRange(100, 500, tolerance=100),
                         children=[
-                            Line(
-                                "Neobank",
-                                key="CCP N26",
-                            ),
+                            Line("Neobank", key="CCP N26"),
                         ],
                     ),
                     Folder(
                         "Monthly",
                         target=TargetRange(1000, 2000, tolerance=500),
                         children=[
-                            Line(
-                                "Online Bank",
-                                key="CCP Boursorama",
-                            ),
-                            Line(
-                                "Traditional Bank",
-                                key="CCP Banque Postale",
-                            ),
+                            Line("Online Bank", key="CCP Boursorama"),
+                            Line("Traditional Bank", key="CCP Banque Postale"),
                         ],
                     ),
                     SharedFolder(
@@ -195,11 +206,37 @@
     """
     copilot = Copilot()  # TODO Coming soon(ish-ish)!
 
-    # Run all routines and display results in the terminal
-    Assistant(
+    """
+    Run the Assistant to get a complete overview of your portfolio!
+    See the available options in the README file or the online documentation.
+    """
+    assistant = Assistant(
         portfolio,
+        buckets=[bucket_garanti],
+        envelopes=[my_bank, my_av],
         ignore_orphans=True,  # Ignore fetched lines that you didn't reference in your portfolio.
         hide_amounts=False,  # Display your portfolio with dots instead of the real values (easier to share).
         hide_root=False,  # Display your portfolio without the root (cosmetic preference).
         show_data=True,  # Show what has been fetched online (e.g. from your Finary account)
-    ).run()  # noqa
+    )
+
+    """
+    Finalynx needs to know where to fetch your data from. You can either
+    use the built-in fetchers (see the README file or the online documentation)
+    or define your own fetchers.
+    """
+    # from finalynx.fetch.source_realt import SourceRealT # move this line to the top of the file
+    # assistant.add_source(SourceRealT("0xMY_REALT_TOKEN"))
+
+    """
+    Run the Assistant to get a complete overview of your portfolio! The run()
+    method will fetch your data, compute your portfolio, and display it.
+    Optionally, you can use the other methods availavle in the `Assistant` class
+    to have more control over the process as run() is just a shortcut.
+    """
+    assistant.run()
+
+    """
+    Optionally, you can launch a web dashboard to get an interactive view!
+    """
+    assistant.dashboard()
diff --git a/examples/tutorials/10_targets.py b/examples/tutorials/10_targets.py
@@ -0,0 +1 @@
+# TODO Coming soon!
diff --git a/examples/tutorials/1_minimal.py b/examples/tutorials/1_minimal.py
@@ -0,0 +1,26 @@
+"""
+Finalynx - Tutorial 1 - Minimal configuration
+=============================================
+
+This tutorial shows how to create the smallest valid portfolio
+configuration with a single line.
+
+Try it out by running:
+> python3 examples/tutorials/1_minimal.py
+
+See explanations and details in the online documentation at:
+> https://finalynx.readthedocs.io
+"""
+# noreorder
+from finalynx import Assistant, Portfolio
+
+
+# Create a portfolio definition (empty for now), this will be your custom
+# structure later on. See the next tutorials for more details.
+portfolio = Portfolio()
+
+
+# Run the assistant to fetch your investments from Finary and add them to your portfolio
+# Optionally, set the `ignore_orphans` option to True to ignore investments that are not
+# in your portfolio definition. Otherwise, they will be added to the portfolio root:
+Assistant(portfolio, ignore_orphans=True).run()  # Default is False