Installation docs update (#1927)

soxoj · Dec 3, 2024 · e982be4 · e982be4
1 parent 1a8bbe7
commit e982be4
Show file tree

Hide file tree

Showing 9 changed files with 83 additions and 45 deletions.
diff --git a/docs/source/development.rst b/docs/source/development.rst
@@ -4,7 +4,7 @@ Development
 ==============
 
 Frequently Asked Questions
-------------------------- 
+--------------------------
 
 1. Where to find the list of supported sites?
 
@@ -177,7 +177,7 @@ PyPi package.
 8. That's all, now you can simply wait push to PyPi. You can monitor it in Action page: https://github.com/soxoj/maigret/actions/workflows/python-publish.yml
 
 Documentation updates
---------------------
+---------------------
 
 Documentations is auto-generated and auto-deployed from the ``docs`` directory.
 
@@ -188,3 +188,13 @@ To manually update documentation:
 3. Run ``make singlehtml`` in the terminal in the docs directory.
 4. Open ``build/singlehtml/index.html`` in your browser to see the result.
 5. If everything is ok, commit and push your changes to GitHub. 
+
+Roadmap
+-------
+
+.. warning::
+   This roadmap requires updating to reflect the current project status and future plans.
+
+.. figure:: https://i.imgur.com/kk8cFdR.png   
+   :target: https://i.imgur.com/kk8cFdR.png
+   :align: center
diff --git a/docs/source/features.rst b/docs/source/features.rst
@@ -155,8 +155,9 @@ It allows getting additional info about the person and checking the existence of
 
 .. _extracting-information-from-pages:
 
-Extracting information from pages
----------------------------------
+Extractiion of information from account pages
+---------------------------------------------
+
 Maigret can parse URLs and content of web pages by URLs to extract info about account owner and other meta information.
 
 You must specify the URL with the option ``--parse``, it's can be a link to an account or an online document. List of supported sites `see here <https://github.com/soxoj/socid-extractor#sites>`_.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -26,8 +26,8 @@ about a person of interest by a username and integrate it with other tools in au
 You may be interested in:
 -------------------------
 - :doc:`Quick start <quick-start>`
-- :doc:`Command line options description <command-line-options>`
 - :doc:`Usage examples <usage-examples>`
+- :doc:`Command line options <command-line-options>`
 - :doc:`Features list <features>`
 
 .. toctree::
@@ -44,4 +44,3 @@ You may be interested in:
    tags
    settings
    development
-   roadmap
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -3,6 +3,10 @@
 Installation
 ============
 
+Maigret can be installed using pip, Docker, or simply can be launched from the cloned repo.
+Also, it is available online via `official Telegram bot <https://t.me/osint_maigret_bot>`_,
+source code of a bot is `available on GitHub <https://github.com/soxoj/maigret-tg-bot>`_.
+
 Package installing
 ------------------
 
@@ -38,6 +42,37 @@ Development version (GitHub)
    pip3 install poetry
    poetry run maigret
 
+Cloud shells and Jupyter notebooks
+----------------------------------
+
+In case you don't want to install Maigret locally, you can use cloud shells and Jupyter notebooks.
+
+.. image:: https://user-images.githubusercontent.com/27065646/92304704-8d146d80-ef80-11ea-8c29-0deaabb1c702.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/soxoj/maigret&tutorial=README.md
+   :alt: Open in Cloud Shell
+
+.. image:: https://replit.com/badge/github/soxoj/maigret
+   :target: https://repl.it/github/soxoj/maigret
+   :alt: Run on Replit
+   :height: 50
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+   :target: https://colab.research.google.com/gist/soxoj/879b51bc3b2f8b695abb054090645000/maigret-collab.ipynb
+   :alt: Open In Colab
+   :height: 45
+
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gist/soxoj/9d65c2f4d3bec5dd25949197ea73cf3a/HEAD
+   :alt: Open In Binder
+   :height: 45
+
+Windows standalone EXE-binaries
+-------------------------------
+
+Standalone EXE-binaries for Windows are located in the `Releases section <https://github.com/soxoj/maigret/releases>`_ of GitHub repository.
+
+Currently, the new binary is created automatically after each commit to the main branch, but is not deployed to the Releases section automatically.
+
 Docker
 ------
 

diff --git a/docs/source/maigret_screenshot.png b/docs/source/maigret_screenshot.png
diff --git a/docs/source/quick-start.rst b/docs/source/quick-start.rst
@@ -10,12 +10,6 @@ After :doc:`installing Maigret <installation>`, you can begin searching by provi
 Maigret will search for accounts with the specified usernames across a vast number of websites. It will provide you with a list 
 of URLs to any discovered accounts, along with relevant information extracted from those profiles.
 
-.. note::
-   Maigret will search for accounts on a huge number of sites,
-   and some of them may return false positive results. At the moment, we are working on autorepair mode to deliver 
-   the most accurate results. 
-
-   If you experience many false positives, you can do the following:
-
-   - Install the last development version of Maigret from GitHub
-   - Run Maigret with ``--self-check`` flag and agree on disabling of problematic sites
+.. image:: maigret_screenshot.png
+   :alt: Maigret search results screenshot
+   :align: center
diff --git a/docs/source/roadmap.rst b/docs/source/roadmap.rst
diff --git a/docs/source/settings.rst b/docs/source/settings.rst
@@ -3,6 +3,9 @@
 Settings
 ==============
 
+.. warning::
+   The settings system is under development and may be subject to change.
+
 Options are also configurable through settings files. See
 `settings JSON file <https://github.com/soxoj/maigret/blob/main/maigret/resources/settings.json>`_
 for the list of currently supported options.

diff --git a/docs/source/usage-examples.rst b/docs/source/usage-examples.rst
@@ -3,49 +3,66 @@
 Usage examples
 ==============
 
-Start a search for accounts with username ``machine42`` on top 500 sites from the Maigret DB.
+1. Search for accounts with username ``machine42`` on top 500 sites (by default, according to Alexa rank) from the Maigret DB.
 
 .. code-block:: console
 
   maigret machine42
 
-Start a search for accounts with username ``machine42`` on **all sites** from the Maigret DB.
+2. Search for accounts with username ``machine42`` on **all sites** from the Maigret DB.
 
 .. code-block:: console
 
   maigret machine42 -a
 
-Start a search [...] and generate HTML and PDF reports.
+.. note::
+   Maigret will search for accounts on a huge number of sites,
+   and some of them may return false positive results. At the moment, we are working on autorepair mode to deliver 
+   the most accurate results. 
+
+   If you experience many false positives, you can do the following:
+
+   - Install the last development version of Maigret from GitHub
+   - Run Maigret with ``--self-check`` flag and agree on disabling of problematic sites
+
+3. Search for accounts with username ``machine42`` and generate HTML and PDF reports.
 
 .. code-block:: console
 
-  maigret machine42 -a -HP
+  maigret machine42 -HP
+
+or
+
+.. code-block:: console
+
+  maigret machine42 -a --html --pdf
+
 
-Start a search for accounts with username ``machine42`` only on Facebook.
+4. Search for accounts with username ``machine42`` on Facebook only.
 
 .. code-block:: console
 
   maigret machine42 --site Facebook
 
-Extract information from the Steam page by URL and start a search for accounts with found username ``machine42``.
+5. Extract information from the Steam page by URL and start a search for accounts with found username ``machine42``.
 
 .. code-block:: console
 
   maigret --parse https://steamcommunity.com/profiles/76561199113454789 
 
-Start a search for accounts with username ``machine42`` only on US and Japanese sites.
+6. Search for accounts with username ``machine42`` only on US and Japanese sites.
 
 .. code-block:: console
 
   maigret machine42 --tags en,jp
 
-Start a search for accounts with username ``machine42`` only on sites related to software development.
+7. Search for accounts with username ``machine42`` only on sites related to software development.
 
 .. code-block:: console
 
   maigret machine42 --tags coding
 
-Start a search for accounts with username ``machine42`` on uCoz sites only (mostly CIS countries).
+8. Search for accounts with username ``machine42`` on uCoz sites only (mostly CIS countries).
 
 .. code-block:: console