Skip to content

Commit

Permalink
fix(docs): Adding more options for getting started (#16)
Browse files Browse the repository at this point in the history
* Adding comparission to other solutions

* Finished build from source page

* Started install from source page

* Finished alternatives-to-download
  • Loading branch information
Theeoi authored Jan 25, 2024
1 parent fc81fab commit 883f4b0
Show file tree
Hide file tree
Showing 13 changed files with 107 additions and 17 deletions.
Binary file added docs/assets/img/build-3.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/img/build-4.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/img/install-3.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/img/install-4.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/img/source-1.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/img/source-2.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 18 additions & 0 deletions docs/demonstration.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,21 @@ If a recurring task is missing one of the recur properties, it resets the Status
![Archived Task](assets/img/demonstration-4.PNG)

If a task is marked as Archived it is ignored and does not recur.

## Why is this Preferrable to Other Options?

There are other solutions to achieving recurring tasks in Notion. Below are some examples comparing them to this software.

### Notion built in Recurring Templates

My personal preference is always to try and stick to native solutions. The [Notion Recurring Templates](https://www.notion.so/help/guides/automate-work-repeating-database-templates) are a good addition to Notion but they are lacking in the recurring tasks front. You are able to configure a recurring template to have a due date on the date they recur. Meaning that immediately when the task is created it is also due. To me this does not cut it since for some tasks I want to have them on my mind before they are due. This software creates the new task when the old one is done allowing you to see the upcoming due date with a database view.

Additionally, I believe that recurring tasks should be as similar to regular tasks as possible. Having the recurring tasks as unique templates on the database leads to clutter on the template dropdown. The recurring tasks should be a set-and-forget kind of thing and not something you have to scroll through when looking for that task template you are after.

One downside to using this software compared to recurring templates is that the recurring tasks are *updated* and not *copied*. This means that if you rely on being able to track the amount of tasks you have done over a longer period of time these recurring tasks will not be able to be tracked. Unless you are using some Notion magic I am unaware of.. That tasks are updated rather than copied could be implemented as an optional feature in the future though.

### Thomas Franks Implementation

[Thomas Franks implementation](https://thomasjfrank.com/notion-automated-recurring-tasks/) is very similar to this software. However, it requires some additional properties on the database that I don't feel are necessary. Specifically the requirement to set up a 'Next Due' formula property and the quite wonky implementation of the 'Days' property.

This software focuses on adding as little overhead as possible to your databases while still getting the functionality in place. The days functionality (being able to specify which days of the week a task should recur) could be useful in some circumstances and might be implemented as an optional property to this software in the future.
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Notion is a great productivity tool for tracking goals, projects and tasks. Howe

## Getting Started [Quickly]

If you are getting started with the software for the first time is it recommended that you follow the full [Getting Started Tutorial](tutorial/getting-started.md). If not, here is a quick rundown of what needs to be done:
If you are getting started with the software for the first time is it recommended that you follow the full [Getting Started Tutorial](tutorial/getting-started/index.md). If not, here is a quick rundown of what needs to be done:

1. Download a [release of the program](https://github.com/Theeoi/notion-recurring-tasks/releases)
- Executable or Source code (Executable recommended for most users)
Expand Down
1 change: 0 additions & 1 deletion docs/tutorial/build-from-source.md

This file was deleted.

72 changes: 72 additions & 0 deletions docs/tutorial/getting-started/alternatives-to-download.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Alternatives to Downloading the Finished Executable

The easiest way of getting started with this software is to download the included executable files from the releases. However, if you would like to take an alternative route to getting the software on your computer you can. These are your alternatives:

- Install the software to a Python environment
- Build your own executable file

No matter which alternative you choose you must download the source code onto your computer. All options require some computer prowess in navigating a terminal window and executing a few commands. After having followed these steps you should continue the [Getting Started tutorial](index.md#setting-up-your-notion-integration) to set up your Notion database and integration.

## Prerequisites

### Getting the Source Code

The first step is to get the source code and be able to explore it through a terminal window.

The source code is available with every release on the [release page on Github](https://github.com/Theeoi/notion-recurring-tasks/releases). Download the Source code and extract it to an appropriate location.

Open a terminal and navigate to the source code. There are multiple ways of doing this but an easy option is to navigate to the extracted folder in a file explorer, right click in the folder and select 'Open in terminal'. If successful you should be able to to type `ls` and see the contents of the directory.

![ls source](../../assets/img/source-1.PNG)

### Activating a Python Virtual Environment

When installing Python packages it is customary to create what is known as a virtual environment and install the package there. This is done as to seperate this install from interfering with other installed Python packages on your system.

Run the following terminal command in the source code directory `python3.12 -m venv .venv`. If you receive an error it could mean that you do not have the correct version of Python installed. [Install Python 3.12](https://www.python.org/downloads/) and retry the above command.

Having created a the virtual environment we can now activate it using the following commands:

- Windows: `.\.venv\Scripts\activate`
- Linux/macOS: `source .venv/bin/activate`

If successful you should see the name of the virtual environment by the commandline.

![Activate venv](../../assets/img/source-2.PNG)

## Installing the Software from Source

### Installing the Software

Having already activated our virtual environment it is very easy to install the software. Run the following command `python -m pip install .` with the virtual environment activated.

If the install was successful you should be able to run the command `pip list` and see all packages installed in the virtual environment.

![pip list](../../assets/img/install-3.PNG)

### Running the Software

The software is now installed within the virtual environment. Run the script using the command `notion-recurring-tasks` with the virtual environment activated.

![Running the software](../../assets/img/install-4.PNG)

## Building an Executable from Source

### Installing the Software and Development Dependencies

To build your own executable you must install the dependencies required to do so. Having already activated our virtual environment it is very easy to install these dependencies. Run the following command `python -m pip install .[dev]` with the virtual environment activated.

If the install was successful you should be able to run the command `pip list` and see all packages installed in the virtual environment.

![pip list dev](../../assets/img/build-3.PNG)

### Building the Executable

Now we are ready to build our executable. The source code includes a helper script to do the heavy lifting for us. Run the script using:

- Windows: `python .\scripts\build_executable.py`
- Linux/macOS: `python scripts/build_executable.py`

The built executable is created in the `dist` directory. Navigate to it either through the terminal or a file explorer. Run the executable as usual.

![Executable in dist directory](../../assets/img/build-4.PNG)
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ Congratulations on deciding to get started using the Notion Recurring Tasks soft

The road ahead can be a little complex if you are not used to working with APIs and Notion databases. But this tutorial will break down the process in four easy-to-follow steps. Once you have completed this tutorial the software and your Notion will be set up for continous use without complications.

And remember, if you have trouble following this tutorial or have any other questions please do not hessitate to reach out through the [support page](../index.md#support).
And remember, if you have trouble following this tutorial or have any other questions please do not hessitate to reach out through the [support page](../../index.md#support).

## Getting the Software

The first step is to get the software onto your computer. There are 3 ways of doing this where the first two revolve around downloading (or cloning) the source code. From there you can either [install the software](install-from-source.md) or [build an executable](build-from-source.md). The third option is to download an already built executable.
The first step is to get the software onto your computer. There are 3 ways of doing this where the first two revolve around downloading (or cloning) the source code and [installing or building the software yourself](alternatives-to-download.md). The third option is to download an already built executable.

For the purposes of this tutorial we will be downloading an already built executable of the software. You should *always* be cautious of downloading an executable from the internet! So if you do not trust the files you are about to download then it is recommended to instead choose one of the above two options.

![Release Assets](../assets/img/getting-started-1.PNG)
![Release Assets](../../assets/img/getting-started-1.PNG)

You can find the software on the [release page on Github](https://github.com/Theeoi/notion-recurring-tasks/releases). On the various releases there are assets as shown in the image above.

Expand All @@ -22,23 +22,23 @@ The source code assets contain a copy of the source code at the time of the rele
If done successfully, you should now have the `notion-recurring-tasks` directory with the content shown below and be able to run it.

![Software Content](../assets/img/getting-started-2.PNG)
![Software Content](../../assets/img/getting-started-2.PNG)

![First Run](../assets/img/getting-started-3.PNG)
![First Run](../../assets/img/getting-started-3.PNG)

## Setting up your Notion Integration

Before moving onward with the software, it is required to allow the software to interact with your Notion. This is done through a [Notion Integration](https://www.notion.so/my-integrations). Navigate to that page and login using your Notion account.

![Notion Integration Page](../assets/img/getting-started-4.PNG)
![Notion Integration Page](../../assets/img/getting-started-4.PNG)

On the Notion Integration page you should see something like the image above. Create your integration by pressing '+ Create new integration' and fill in some basic information like below. It is important to select the Notion Workspace in which your recurring tasks database will be. Choose a name that is descriptive of what the integration does and is easily identifiable. This will help you later.

![New Integration Basicinfo](../assets/img/getting-started-5.PNG)
![New Integration Basicinfo](../../assets/img/getting-started-5.PNG)

![Change Integration Capabilities](../assets/img/getting-started-6.PNG)
![Change Integration Capabilities](../../assets/img/getting-started-6.PNG)

![Copy Integration Secret](../assets/img/getting-started-7.PNG)
![Copy Integration Secret](../../assets/img/getting-started-7.PNG)

After your integration is created you can change its capabilities on the 'Capabilities' page. The Notion Recurring Tasks software only needs access to read and update tasks in your task database, and therefore it is recommended to limit it accordingly.

Expand All @@ -54,20 +54,20 @@ In your task database, every task must have the following properties set up like

> :grey_exclamation: **NOTE**: You can have more task properties than the minimum required. Add these to a new database or integrate the properties with your already existing tasks database.
![Notion Task](../assets/img/getting-started-8.PNG)
![Notion Task](../../assets/img/getting-started-8.PNG)

![Task Properties Overview](../assets/img/getting-started-9.PNG)
![Task Properties Overview](../../assets/img/getting-started-9.PNG)

The final step is to add your previously created Notion integration to this database. *On the page of the database*, press the three dots in the far upper right corner. Go to 'Add connections' and search for the name of your integration. Once added it should show up in the list of connections.

> :grey_exclamation: **NOTE**: Since the connection is added to the database itself and not the workspace, the connection will not be visible on the connections list elsewhere.
![Adding the Integration](../assets/img/getting-started-10.PNG)
![Adding the Integration](../../assets/img/getting-started-10.PNG)

## Running the Software

Congratulations! With your Notion database set up you are ready to run the software and try it out.

As we saw earlier, the software prompts you for your Notion key upon starting up. Copy the secret key from your integration you created earlier and input it to the software. If everything is set up properly the software should print how many tasks it managed to update with a new Due Date according to the set properties. If not (or you are getting an error), please dubble check that everything is set up as instructed above.

If you are still experiencing issues, please get in touch through the [support page](../index.md#support).
If you are still experiencing issues, please get in touch through the [support page](../../index.md#support).
1 change: 0 additions & 1 deletion docs/tutorial/install-from-source.md

This file was deleted.

4 changes: 3 additions & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,9 @@ nav:
- Demonstration: demonstration.md
- Tutorials:
- tutorial/index.md
- Getting Started: tutorial/getting-started.md
- Getting Started:
- tutorial/getting-started/index.md
- Alternatives to Downloading the Finished Executable: tutorial/getting-started/alternatives-to-download.md
- Automatically Running the Software: tutorial/automating-the-software.md
- How-to-Guides:
- how-to-guide/index.md
Expand Down

0 comments on commit 883f4b0

Please sign in to comment.