Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clean up stuff and migrate docs to MyST-Parser #879

Merged
merged 1 commit into from
Apr 16, 2021
Merged

Clean up stuff and migrate docs to MyST-Parser #879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
- Remove debugging line that loads entire files into memory. - `PR #858` - Thanks **asrp**
- Removed terrible isinstance check of unittest.Mock in mirror.py - `PR #859` - Thanks **ichard26**
- Put potential time consuming IO operations into executor - `PR #877`
- Migrated Markdown documentation from recommonmark to MyST-Parser + docs config clean up - `PR #879` - Thanks **ichard26**

# 4.4.0 (2020-12-31)

Expand Down
116 changes: 10 additions & 106 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@
import os


class DocStub:
__version__ = "0.0.0"
__name__ = "Unknown"
Expand All @@ -11,25 +8,16 @@ class DocStub:
except ImportError:
doc_module = DocStub()

try:
from recommonmark.parser import CommonMarkParser # noqa: F401
from recommonmark.transform import AutoStructify

github_doc_root = "https://partner.git.corp.yahoo.com/pages/yahoo.platform_init"
USE_MARKDOWN = True
except ImportError:
USE_MARKDOWN = False

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = "3.0"

# epub build warns about .nojekyll of which Sphinx creates on build,
# so just ignore the warning since we can't do anything a-boat it :D
suppress_warnings = ["epub.unknown_project_files"]

# Just a protection against an incompatible version of recommonmark.
# Just a protection against an incompatible version of MyST-Parser
# The listed version is the minimal version required for that extension.
needs_extensions = {"recommonmark": "0.5"}
needs_extensions = {"myst_parser": "0.13.0"}

extensions = [
"sphinx.ext.autodoc",
Expand All @@ -42,16 +30,14 @@ class DocStub:
"sphinx.ext.graphviz",
"sphinx.ext.inheritance_diagram",
"sphinx.ext.githubpages",
"recommonmark",
"myst_parser",
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# The suffix of source filenames.
source_suffix = [".rst"]
if USE_MARKDOWN:
source_suffix.append(".md")
source_suffix = [".rst", ".md"]

# The encoding of source files.
# source_encoding = 'utf-8-sig'
Expand Down Expand Up @@ -115,6 +101,9 @@ class DocStub:
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# Enable certain MyST-Parser extensions
# see also: https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
myst_enable_extensions = ["colon_fence"]

# -- Options for HTML output ----------------------------------------------

Expand Down Expand Up @@ -202,83 +191,13 @@ class DocStub:
html_theme = "default"

# Determine available themes and settings
available_themes = ["default"]
available_theme_settings = {}
try:
import cloud_sptheme as csp

available_themes.insert(0, "cloudsp")
available_theme_settings["cloudsp"] = {}
available_theme_settings["cloudsp"]["theme"] = "cloud"
available_theme_settings["cloudsp"]["path"] = [csp.get_theme_dir()]
available_theme_settings["cloudsp"]["options"] = {"roottarget": "index"}
except ImportError:
pass

try:
import sphinx_bootstrap_theme

available_themes.insert(0, "bootstrap")
available_theme_settings["bootstrap"] = {}
available_theme_settings["bootstrap"]["theme"] = "bootstrap"
available_theme_settings["bootstrap"][
"path"
] = sphinx_bootstrap_theme.get_html_theme_path()
available_theme_settings["bootstrap"]["options"] = {
# lumen, journal
"bootswatch_theme": os.environ.get("SPHINX_BOOTSWATCH_THEME", "journal")
}
except ImportError:
pass

try:
import guzzle_sphinx_theme

available_themes.insert(0, "guzzle")
available_theme_settings["guzzle"] = {}
available_theme_settings["guzzle"]["theme"] = "guzzle_sphinx_theme"
available_theme_settings["guzzle"]["path"] = guzzle_sphinx_theme.html_theme_path()
available_theme_settings["guzzle"]["options"] = {}
except ImportError:
pass

try:
import sphinx_rtd_theme

available_themes.insert(0, "read_the_docs")
available_theme_settings["read_the_docs"] = {}
available_theme_settings["read_the_docs"]["theme"] = "sphinx_rtd_theme"
available_theme_settings["read_the_docs"]["path"] = [
sphinx_rtd_theme.get_html_theme_path()
]
available_theme_settings["read_the_docs"]["options"] = {
"collapse_navigation": os.environ.get("SPHINX_COLLAPSE_NAVIGATION", True),
"display_version": os.environ.get("SPHINX_DISPLAY_VERSION", version != "0.0.0"),
"navigation_depth": os.environ.get("SPHINX_NAVIGATION_DEPTH", 3),
}
except ImportError:
pass

try:
import pypa_theme # noqa: F401

available_themes.insert(0, "pypa")
available_theme_settings["pypa"] = {}
available_theme_settings["pypa"]["theme"] = "pypa_theme"
available_theme_settings["pypa"]["path"] = []
available_theme_settings["pypa"]["options"] = {}
html_theme = "pypa_theme"
except ImportError:
pass

selected_theme = os.environ.get("SPHINX_THEME", available_themes[0])
if selected_theme not in available_themes:
selected_theme = available_themes[0]
print(f"SPHINX_THEME is not installed, using {selected_theme!r} theme")

html_theme = available_theme_settings[selected_theme]["theme"]
html_theme_path = available_theme_settings[selected_theme]["path"]
if available_theme_settings[selected_theme].get("options", None):
html_theme_options = available_theme_settings[selected_theme]["options"]
print("WARNING: 'pypa_theme' isn't available, falling back to 'default' HTML theme")
html_theme = "default"
Comment on lines -266 to +200
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Much more sane! Thanks.


# -- Options for LaTeX output ---------------------------------------------

Expand Down Expand Up @@ -378,18 +297,3 @@ class DocStub:

# Useful external link shortcuts
extlinks = {"issue": ("https://github.com/sphinx-doc/sphinx/issues/%s", "issue ")}


def setup(app):
if USE_MARKDOWN:
print("Adding recommonmark settings")
app.add_config_value(
"recommonmark_config",
{
"url_resolver": lambda url: github_doc_root + url,
"auto_toc_tree_section": "Contents",
"enable_eval_rst": True,
},
True,
)
app.add_transform(AutoStructify)
26 changes: 13 additions & 13 deletions docs/filtering_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Mirror filtering
# Mirror filtering

_NOTE: All references to whitelist/blacklist are deprecated, and will be replaced with allowlist/blocklist in 5.0_

Expand All @@ -13,7 +13,7 @@ converted.
E.g. to Blocklist [discord.py](https://pypi.org/project/discord.py/) the string 'discord-py'
is correct, but 'discord.PY' will also work.

### Plugins Enabling
## Plugins Enabling

The plugins setting is a list of plugins to enable.

Expand All @@ -39,15 +39,15 @@ enabled =
...
```

### allowlist / blocklist filtering settings
## allowlist / blocklist filtering settings

The blocklist / allowlist settings are in configuration sections named **\[blocklist\]** and **\[allowlist\]**
these section provides settings to indicate packages, projects and releases that should /
should not be mirrored from PyPI.

This is useful to avoid syncing broken or malicious packages.

### packages
## packages

The packages setting is a list of python [pep440 version specifier](https://www.python.org/dev/peps/pep-0440/#id51) of packages to not be mirrored. Enable version specifier filtering for blocklist and allowlist packages through enabling the 'blocklist_release' and 'allowlist_release' plugins, respectively.

Expand All @@ -74,7 +74,7 @@ packages =
ptr
```

### Metadata Filtering
## Metadata Filtering
Packages and release files may be selected by filtering on specific metadata value.

General form of configuration entries is:
Expand All @@ -86,7 +86,7 @@ tag:tag:path.to.object =
matchb
```

### requirements files Filtering
## requirements files Filtering
Packages and releases might be given as requirements.txt files

if requirements_path is missing it is assumed to be system root folder ('/')
Expand All @@ -102,7 +102,7 @@ requirements =
requirements.txt
```

#### Project Regex Matching
### Project Regex Matching

Filter projects to be synced based on regex matches against their raw metadata entries straight from parsed downloaded json.

Expand All @@ -119,7 +119,7 @@ Valid tags are `all`,`any`,`none`,`match-null`,`not-null`, with default of `any:
All metadata provided by json is available, including `info`, `last_serial`, `releases`, etc. headings.


#### Release File Regex Matching
### Release File Regex Matching

Filter release files to be downloaded for projects based on regex matches against the stored metadata entries for each release file.

Expand All @@ -139,7 +139,7 @@ containing the package-wide inthe fo, `release` containing the version of the re
for an individual file for that release.


### Prerelease filtering
## Prerelease filtering

Bandersnatch includes a plugin to filter our pre-releases of packages. To enable this plugin simply add `prerelease_release` to the enabled plugins list.

Expand All @@ -149,7 +149,7 @@ enabled =
prerelease_release
```

### Regex filtering
## Regex filtering

Advanced users who would like finer control over which packages and releases to filter can use the regex Bandersnatch plugin.

Expand Down Expand Up @@ -178,7 +178,7 @@ releases =
Note the same `filter_regex` section may include a `packages` and a `releases` entry with any number of regular expressions.


### Platform-specific binaries filtering
## Platform-specific binaries filtering

This filter allows advanced users not interesting in Windows/macOS/Linux specific binaries to not mirror the corresponding files.

Expand All @@ -195,7 +195,7 @@ platforms =
Available platforms are: `windows` `macos` `freebsd` `linux`.


### Keep only latest releases
## Keep only latest releases

You can also keep only the latest releases based on greatest [Version](https://packaging.pypa.io/en/latest/version.html) numbers.

Expand All @@ -213,7 +213,7 @@ By default, the plugin does not filter out any release. You have to add the `kee
You should be aware that it can break requirements. Prereleases are also kept.


### Block projects above a specified size threshold
## Block projects above a specified size threshold

There is an increasing number of projects that consume a large amount of space.
At the time of writing (Jan 2021) the [stats](https://pypi.org/stats/) shows some
Expand Down
4 changes: 2 additions & 2 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
## Installation
# Installation

The following instructions will place the bandersnatch executable in a
virtualenv under `bandersnatch/bin/bandersnatch`.

- bandersnatch **requires** `>= Python 3.8.0`


### pip
## pip

This installs the latest stable, released version.

Expand Down
Loading