Add a Getting Started and improve documentation

.devcontainer/devcontainer.json

@@ -14,8 +14,7 @@
 	"forwardPorts": [8000],
 	"portsAttributes": {
 		"8000": {
-			"label": "Sphinx",
-			"onAutoForward": "openPreview"
+			"label": "Sphinx"
 		}
 	},
 

.github/workflows/ci.yml

@@ -17,6 +17,9 @@ jobs:
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
+      with:
+        sparse-checkout: |
+          src
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
@@ -26,7 +29,7 @@ jobs:
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip pylint black mypy
+        python -m pip install --upgrade pip pylint black mypy sphinx-lint
         pip install -r requirements.txt
 
     - name: Run Pylint
@@ -40,3 +43,7 @@ jobs:
     - name: Run Mypy
       run: |
         mypy $(git ls-files '*.py')
+
+    - name: Run Sphinx Lint
+      run: |
+        sphinx-lint $(git ls-files '*.rst')

.vscode/tasks.json

@@ -27,6 +27,12 @@
         "-e"
       ],
       "problemMatcher": []
+    },
+    {
+      "label": "Build documentation",
+      "type": "shell",
+      "command": "sphinx-autobuild docs/source docs/_build/html",
+      "problemMatcher": []
     }
   ]
 }

docs/source/conf.py

@@ -9,14 +9,15 @@
 project = 'InstaWebhooks'
 copyright = '2024, Ryan Luu'
 author = 'Ryan Luu'
-release = '0.1'
-version = '0.1.3'
+release = '1.0'
+version = '1.0.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx_copybutton'
+    'sphinx_copybutton',
+    'sphinxarg.ext',
 ]
 
 templates_path = ['_templates']
@@ -31,6 +32,28 @@
 html_static_path = ['_static']
 
 html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/RyanLua/InstaWebhooks",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "Read the Docs",
+            "url": "https://readthedocs.org/projects/instawebhooks",
+            "html": """
+                <svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
+                    <path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
     "announcement": "This is a early version of the documentation and not final.",
     "source_repository": "https://github.com/RyanLua/InstaWebhooks",
     "source_branch": "main",

docs/source/getting-started.rst

@@ -0,0 +1,78 @@
+Getting Started
+===============
+
+Learn about getting started with InstaWebhooks to send new Instagram posts any Discord channel from scratch.
+
+Installing InstaWebhooks
+------------------------
+
+With `Python <https://www.python.org/>`_ installed, install InstaWebhooks with `pip <https://pypi.org/project/pip/>`_:
+
+.. code:: console
+
+    $ pip install instawebhooks
+
+Check that InstaWebhooks was installed correctly by seeing if it reports its version:
+
+.. code:: console
+
+    $ instawebhooks --version
+
+Make sure that are on the `latest version of InstaWebhooks <https://pypi.org/project/instawebhooks/>`_.
+
+For more ways to install InstaWebhooks, see the `installation guide <installation.html>`_.
+
+Setting up Discord webhooks
+---------------------------
+
+To get your Discord webhook URL, you need the **Manage Webhooks** permission in the channel you want to send new Instagram posts to.
+
+You can learn more about webhooks through the article, `Intro to Webhooks <https://support.discord.com/hc/en-us/articles/228383668>`_.
+
+Creating your webhook
+^^^^^^^^^^^^^^^^^^^^^
+
+If your already have a webhook, you can skip this step.
+
+#. Open **Server Settings**, then **Integrations**
+#. Click the "**Create Webhook**" button
+
+.. image:: _static/integrations-tab.png
+
+Now you can set the name, channel, and avatar for the webhook.
+
+Getting the webhook URL
+^^^^^^^^^^^^^^^^^^^^^^^
+
+When you have your webhook made, click the "**Copy Webhook URL**" button to copy the URL to your clipboard.
+
+.. image:: _static/webhook-settings.png
+
+The copied URL should look similar this:
+
+.. code:: none
+
+    https://discordapp.com/api/webhooks/0123456789/abcdefghijklmnopqrstuvwxyz
+
+Setting up InstaWebhooks
+------------------------
+
+Now with the webhook URL and a Instagram account in mind, you can set up InstaWebhooks to send new Instagram posts to your Discord channel.
+
+Replace ``<INSTAGRAM_USERNAME>`` with the username of the Instagram account you want to monitor and ``<DISCORD_WEBHOOK_URL>`` with the Discord webhook URL you copied earlier.
+
+.. code:: console
+
+    $ instawebhooks <INSTAGRAM_USERNAME> <DISCORD_WEBHOOK_URL>
+
+It should look something like this:
+
+.. code:: console
+
+    $ instawebhooks raenlua https://discord.com/api/webhooks/0123456789/abcdefghijklmnopqrstuvwxyz
+
+Now, whenever the Instagram account `@raenlua` posts a new photo, it will be sent to the Discord webhook.
+
+.. image:: _static/webhook-message.png
+
+For more information about using InstaWebhooks, see the `usage guide <usage.html>`_.

docs/source/index.rst

@@ -8,6 +8,10 @@ InstaWebhooks documentation
 
 InstaWebhooks is a `Python <https://www.python.org/>`_ command-line interface which allows you to monitor any Instagram account for new posts and then send them to a `Discord webhook <https://discord.com/developers/docs/resources/webhook>`_.
 
+* Works with **any Instagram account**, including private accounts if you are a follower
+* Customizable **Discord embeds** for new posts and message contents including **mentions/pings**
+* **User-definable refresh interval** for checking for new posts the second they are posted
+
 Quickstart
 ----------
 
@@ -30,13 +34,14 @@ Contents
 
 .. toctree::
 
+   getting-started
    installation
    usage
 
 .. toctree::
    :caption: Project
 
-   Contributing <https://github.com/RyanLua/InstaWebhooks/blob/docs-site/CONTRIBUTING.md>
-   Code of Conduct <https://github.com/RyanLua/InstaWebhooks/tree/docs-site?tab=coc-ov-file#readme>
+   Contributing <https://github.com/RyanLua/InstaWebhooks/blob/main/CONTRIBUTING.md>
+   Code of Conduct <https://github.com/RyanLua/InstaWebhooks/tree/main?tab=coc-ov-file#readme>
    GitHub <https://github.com/RyanLua/InstaWebhooks>
-   PyPI <https://pypi.org/project/instawebhooks>
+   PyPI <https://pypi.org/project/instawebhooks>

docs/source/installation.rst

@@ -90,4 +90,4 @@ Installing from source code is another option to contribute or use the latest de
 
 .. code:: console
 
-    $ pip install --editable .
+    $ pip install --editable .

docs/source/usage.rst

@@ -6,75 +6,35 @@ To see the available options and arguments, run the following command:
 .. code:: console
 
     $ instawebhooks --help
-    usage: instawebhooks [-h] [-q | -v] [-i REFRESH_INTERVAL] [-c MESSAGE_CONTENT] [-e] [--version]
-                         instagram_username discord_webhook_url
-
-    Monitor Instagram accounts for new posts and send them to a Discord webhook
-
-    positional arguments:
-      instagram_username    the Instagram username to monitor for new posts
-      discord_webhook_url   the Discord webhook URL to send new posts to
-
-    options:
-      -h, --help            show this help message and exit
-      -q, --quiet           hide all logging
-      -v, --verbose         show debug logging
-      -i REFRESH_INTERVAL, --refresh-interval REFRESH_INTERVAL
-                            time in seconds to wait before checking for new posts again
-      -c MESSAGE_CONTENT, --message-content MESSAGE_CONTENT
-                            the message content to send with the webhook
-      -e, --no-embed        don't show the post embed and only send message content
-      --version             show program's version number and exit
-
-    https://github.com/RaenLua/InstaWebhooks
-
-Below, learn how to use InstaWebhooks and what you can do with it.
 
 Examples
 --------
 
-In the below templates, replace ``<INSTAGRAM_USERNAME>`` with the Instagram username you want to monitor and ``<DISCORD_WEBHOOK_URL>`` with the Discord webhook URL you want to send new posts to.
-
-Your command should look similar to this:
-
-.. code:: console
-
-    $ instawebhooks raenlua https://discord.com/api/webhooks/0123456789/abcdefghijklmnopqrstuvwxyz
-
-Templates
----------
-
-Example templates for using InstaWebhooks are provided below. Note to change the Instagram username and Discord webhook URL to your own.
-
-.. note::
-
-    The default refresh interval is 1 hour (3600 seconds), and the default message content is an empty string.
-
-Send new posts every hour:
+* Send new posts:
 
 .. code:: console
 
     $ instawebhooks <INSTAGRAM_USERNAME> <DISCORD_WEBHOOK_URL>
 
-Send new posts every hour with verbose logging:
+* Send new posts with verbose logging:
 
 .. code:: console
 
     $ instawebhooks -v <INSTAGRAM_USERNAME> <DISCORD_WEBHOOK_URL>
 
-Send new posts every 30 minutes:
+* Send new posts every 30 minutes:
 
 .. code:: console
 
     $ instawebhooks -i 1800 <INSTAGRAM_USERNAME> <DISCORD_WEBHOOK_URL>
 
-Send new posts every hour with a custom message:
+* Send new posts with a custom message:
 
 .. code:: console
 
     $ instawebhooks -c "New post from {owner_name}: {post_url}" <INSTAGRAM_USERNAME> <DISCORD_WEBHOOK_URL>
 
-Send new posts every hour with no embed and a custom message:
+* Send new posts with no embed and a custom message:
 
 .. code:: console
 
@@ -83,77 +43,22 @@ Send new posts every hour with no embed and a custom message:
 Reference
 ---------
 
-Positional Arguments
-~~~~~~~~~~~~~~~~~~~~
-
-``INSTAGRAM_USERNAME``
-
-    The Instagram username to monitor for new posts.
-
-    Usernames must follow the Instagram username format:
-
-    * Starts with a letter or underscore.
-    * Does not contain consecutive periods.
-    * Is between 2 and 30 characters long.
-    * Ends with an alphanumeric character or underscore.
-
-``DISCORD_WEBHOOK_URL``
-
-    The Discord webhook URL to send new posts to.
-
-    URLs must follow the Discord webhook URL format:
-
-    * ``https://discord.com/api/webhooks/{webhook_id}/{webhook_token}``
-    * ``https://discordapp.com/api/webhooks/{webhook_id}/{webhook_token}``
-
-Optional Arguments
-~~~~~~~~~~~~~~~~~~
-
-``-h, --help``
-
-    Show this help message and exit.
-
-``-v, --verbose``
-
-    Enable verbose logging.
-
-    Changes the logging level to debug, showing the following logs in addition to the default info logs:
-
-    * When a check for new posts is started.
-    * If a new post is found or not.
-    * When a post is sent to Discord.
-
-``-i REFRESH_INTERVAL, --refresh-interval REFRESH_INTERVAL``
-
-    .. caution::
-
-        Do not set the refresh interval too low or you may be `rate limited by Instagram <https://instaloader.github.io/troubleshooting.html#too-many-requests>`_.
-
-    The refresh interval to check for new posts in seconds (default: 3600).
-
-``-c MESSAGE_CONTENT, --message-content MESSAGE_CONTENT``
-
-    The message content to send to Discord (default: "").
-
-    Accepts placeholders for the post information:
+.. argparse::
+   :module: instawebhooks.parser
+   :func: parser
+   :prog: instawebhooks
+   :noepilog:
 
-    * ``{post_url}`` - The URL to the post on Instagram
-        * ``https://www.instagram.com/C8wRGmyR-6N``
-    * ``{owner_url}`` - The URL to the owner's profile on Instagram
-        * ``https://www.instagram.com/raenlua``
-    * ``{owner_name}`` - The owner's full name
-        * ``Ryan Luu``
-    * ``{owner_username}`` - The owner's username
-        * ``raenlua``
-    * ``{post_caption}`` - The post's caption
-        * ``This is a post caption.``
-    * ``{post_shortcode}`` - The post's shortcode
-        * ``C8wRGmyR-6N``
-    * ``{post_image_url}`` - The post's image URL
-        * ``https://www.instagram.com/p/C8wRGmyR-6N/media``
+   instagram_username : @after
+        Usernames must follow the Instagram username format:
 
-``-e, --no-embed``
+        * Starts with a letter or underscore.
+        * Does not contain consecutive periods.
+        * Is between 2 and 30 characters long.
+        * Ends with an alphanumeric character or underscore.
 
-    Don't show the post embed and only send message content
+   discord_webhook_url : @after
+        URLs must follow the Discord webhook URL format:
 
-    A message content must be provided when using this option. Empty messages cannot be sent.
+        * ``https://discord.com/api/webhooks/{webhook_id}/{webhook_token}``
+        * ``https://discordapp.com/api/webhooks/{webhook_id}/{webhook_token}``