mirror of
https://github.com/soxoj/maigret.git
synced 2026-08-17 19:25:41 +02:00
Improved documentation, added quick link to deploy Maigret web to Readme (#2952)
* Improved documentation, added quick link to deploy Maigret web to Readme * Move Render config file to utils/
This commit is contained in:
Soxoj
@@ -290,6 +290,12 @@ Run `maigret --help` for all options. Docs: [CLI options](https://maigret.readth
|
||||
|
||||
Maigret has a built-in web UI with a results graph and downloadable reports.
|
||||
|
||||
Don't want to run it yourself? Deploy the published `soxoj/maigret:web` Docker image as a hosted app in one click:
|
||||
|
||||
<a href="https://render.com/deploy?repo=https://github.com/soxoj/maigret&path=utils/render.yaml"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" height="40"></a>
|
||||
|
||||
Runs on Render's free tier (spins down after 15 min idle, spins back up on the next request). No login is set up on the instance, so anyone with the URL can use it.
|
||||
|
||||
<details>
|
||||
<summary>Web Interface Screenshots</summary>
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
// Show a helper when a docs search returns zero results.
|
||||
//
|
||||
// A large share of searches on these docs are usernames, emails or phone
|
||||
// numbers typed by people who think this page *is* Maigret. Those always return
|
||||
// nothing, so the empty-results state is the moment to point them at how to run
|
||||
// a real search.
|
||||
//
|
||||
// There are two search UIs to cover:
|
||||
// 1. Read the Docs Addons modal (production hosting) — a <readthedocs-search>
|
||||
// web component with an OPEN shadow root; on zero hits it renders a
|
||||
// `.no-results` panel.
|
||||
// 2. Plain Sphinx search.html (local builds, non-RTD hosting) — results go in
|
||||
// #search-results.
|
||||
// Both are keyed off DOM structure only, and every lookup is null-guarded, so a
|
||||
// markup change upstream just means the helper stops appearing — never an error.
|
||||
|
||||
(function () {
|
||||
"use strict";
|
||||
|
||||
var HELPER_HTML =
|
||||
"<strong>Looking for a person, not documentation?</strong><br>" +
|
||||
"This searches Maigret’s docs — not social networks. To check a " +
|
||||
"username, run <code>maigret <username></code> in a terminal, use the " +
|
||||
'<a href="https://sites.google.com/view/maigret-bot-link">Telegram bot</a>, ' +
|
||||
"or run <code>maigret --web 5000</code>.";
|
||||
|
||||
// The RTD modal lives in a shadow root, so the theme's .admonition CSS can't
|
||||
// reach it — style inline there. On the light-DOM Sphinx page, reuse the theme.
|
||||
function makeBox(inShadow) {
|
||||
var box = document.createElement("div");
|
||||
box.id = "maigret-search-help";
|
||||
box.innerHTML = HELPER_HTML;
|
||||
if (inShadow) {
|
||||
box.style.cssText =
|
||||
"margin:16px auto;max-width:88%;padding:12px 16px;border:1px solid " +
|
||||
"#cfe3c9;background:#e8f5e2;border-radius:6px;font-size:14px;" +
|
||||
"line-height:1.55;text-align:left;color:#1a1a1a";
|
||||
} else {
|
||||
box.className = "admonition tip";
|
||||
}
|
||||
return box;
|
||||
}
|
||||
|
||||
// Surface 1 — Read the Docs Addons search modal.
|
||||
function hookRtdSearch() {
|
||||
if (!window.customElements || !customElements.whenDefined) return;
|
||||
customElements.whenDefined("readthedocs-search").then(function () {
|
||||
var tries = 0;
|
||||
(function attach() {
|
||||
var el = document.querySelector("readthedocs-search");
|
||||
var root = el && el.shadowRoot;
|
||||
if (!root) {
|
||||
if (tries++ < 20) setTimeout(attach, 250);
|
||||
return;
|
||||
}
|
||||
// .no-results is re-rendered on each keystroke; re-inject when missing.
|
||||
new MutationObserver(function () {
|
||||
var nr = root.querySelector(".no-results");
|
||||
if (nr && !nr.querySelector("#maigret-search-help")) {
|
||||
nr.insertBefore(makeBox(true), nr.querySelector(".tips") || null);
|
||||
}
|
||||
}).observe(root, { childList: true, subtree: true });
|
||||
})();
|
||||
});
|
||||
}
|
||||
|
||||
// Surface 2 — plain Sphinx search.html.
|
||||
function hookSphinxSearch() {
|
||||
var out = document.getElementById("search-results");
|
||||
if (!out) return;
|
||||
function maybeShow() {
|
||||
if (document.getElementById("maigret-search-help")) return; // once
|
||||
if (!new URLSearchParams(window.location.search).get("q")) return; // no query
|
||||
if (out.querySelector("li")) return; // has results
|
||||
if (!out.textContent.trim()) return; // search not finished yet
|
||||
out.insertBefore(makeBox(false), out.firstChild);
|
||||
}
|
||||
// ponytail: debounce settles the async result stream; 250ms is ample since
|
||||
// 0-result runs finish in one tick. Bump if a slow render ever false-fires.
|
||||
var settle;
|
||||
new MutationObserver(function () {
|
||||
clearTimeout(settle);
|
||||
settle = setTimeout(maybeShow, 250);
|
||||
}).observe(out, { childList: true, subtree: true, characterData: true });
|
||||
}
|
||||
|
||||
document.addEventListener("DOMContentLoaded", function () {
|
||||
hookRtdSearch();
|
||||
hookSphinxSearch();
|
||||
});
|
||||
})();
|
||||
@@ -43,6 +43,8 @@ templates_path = ['_templates']
|
||||
# -- Options for HTML output
|
||||
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_static_path = ['_static']
|
||||
html_js_files = ['maigret_search_help.js']
|
||||
|
||||
# -- Options for EPUB output
|
||||
epub_show_urls = 'footnote'
|
||||
|
||||
@@ -173,3 +173,75 @@ GDK-PixBuf). Per-OS install steps are in the
|
||||
|
||||
For other report formats (``--html``, ``--md``, ``--json``, ``--csv``,
|
||||
``--txt``, ``--xmind``), see :doc:`command-line-options`.
|
||||
|
||||
``maigret: command not found``
|
||||
------------------------------
|
||||
|
||||
The install succeeded but your shell can't find the ``maigret`` launcher
|
||||
(you may see ``-bash: maigret: command not found`` or a *not recognized*
|
||||
message on Windows). The package is installed — only the entry-point
|
||||
script is not on your ``PATH``. Fixes, in order of laziness:
|
||||
|
||||
- Run it as a module instead — this always works if the package imported:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
python3 -m maigret <username>
|
||||
|
||||
- ``pip install --user`` puts the script in a per-user ``bin`` /
|
||||
``Scripts`` directory that is often not on ``PATH``. The cleanest fix is
|
||||
to install into an isolated environment that manages ``PATH`` for you:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pipx install maigret
|
||||
|
||||
- On Windows, reopen the terminal after installing (``PATH`` is only read
|
||||
at startup), or use the standalone ``maigret_standalone.exe`` — see
|
||||
:doc:`installation`.
|
||||
|
||||
``error: metadata-generation-failed``
|
||||
-------------------------------------
|
||||
|
||||
This comes from **pip**, not Maigret: pip could not build one of the
|
||||
dependencies. Almost always the build toolchain is stale or a native
|
||||
dependency is missing its system libraries. Try, in order:
|
||||
|
||||
- Upgrade the toolchain and retry:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
python -m pip install --upgrade pip setuptools wheel
|
||||
|
||||
- Use a supported interpreter (Python 3.10–3.12). Bleeding-edge or
|
||||
end-of-life versions frequently have no prebuilt wheels, forcing a
|
||||
source build that then fails.
|
||||
- If the failing package is a native one (``lxml``, ``reportlab``,
|
||||
``_renderPM``, or an error mentioning ``ft2build.h`` / ``cairo``), you
|
||||
need system build dependencies — see the *Troubleshooting* section of
|
||||
:doc:`installation`, or skip the compilers entirely and use Docker.
|
||||
|
||||
``Too many errors of type "..."``
|
||||
---------------------------------
|
||||
|
||||
This is Maigret's **end-of-run summary**, not a crash — the run finished.
|
||||
It means a large share of sites failed the *same* way, so the fix depends
|
||||
on the class printed in the quotes:
|
||||
|
||||
- ``Connecting failure`` — check your internet connection; if only a
|
||||
subset of sites fails, lower parallelism with ``-n 10``.
|
||||
- ``Connecting failure (DNS)`` — DNS resolution failed for most sites.
|
||||
Try ``--dns-resolver threaded`` (often fixes Windows / VPN / corporate
|
||||
networks); failing that, check your VPN / firewall and consider a public
|
||||
resolver (``1.1.1.1`` or ``8.8.8.8``).
|
||||
- ``Request timeout`` — raise ``--timeout`` or switch ISP / network.
|
||||
- ``Captcha`` — switch to another IP address, or supply service cookies.
|
||||
- ``Bot protection`` / ``Access denied`` — switch IP; a residential
|
||||
``--proxy`` or ``--cloudflare-bypass`` is the usual fix.
|
||||
- ``Webgate unavailable`` — ``--cloudflare-bypass`` is on but no solver is
|
||||
reachable; start FlareSolverr, or drop the flag to skip protected sites.
|
||||
|
||||
If most of your run is one of the last three, see the
|
||||
*Sites fail / timeout / return 403* section above and the full
|
||||
`TROUBLESHOOTING.md
|
||||
<https://github.com/soxoj/maigret/blob/main/TROUBLESHOOTING.md>`_.
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
services:
|
||||
- type: web
|
||||
name: maigret-web
|
||||
runtime: image
|
||||
image:
|
||||
url: docker.io/soxoj/maigret:web
|
||||
plan: free
|
||||
Reference in New Issue
Block a user