Merge pull request #28 from RyanLua/polish-docs

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

@@ -4,6 +4,7 @@ on:
   push:
     paths:
       - '**.py'
+      - '**.rst'
       - '.github/workflows/ci.yml'
 
 jobs:
@@ -26,17 +27,21 @@ 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
       run: |
-        pylint $(git ls-files '*.py')
+        pylint $(git ls-files 'src/**/*.py')
 
     - name: Run Black
       run: |
-        black $(git ls-files '*.py') --check
+        black $(git ls-files 'src/**/*.py') --check
 
     - name: Run Mypy
       run: |
-        mypy $(git ls-files '*.py')
+        mypy $(git ls-files 'src/**/*.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

@@ -3,20 +3,32 @@
 # For the full list of built-in configuration values, 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 -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 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 +43,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 .