def on_github_pages(
directory: str = "",
config_file: str = "pyproject.toml",
message: str = None,
force: bool = False,
ignore_version: bool = False,
modules: list = None,
) -> None:
"""Regenerates and deploys the documentation to GitHub pages.
- *directory*: The root folder of your project.
- *config_file*: The [TOML](https://github.com/toml-lang/toml#toml) formatted
config file you wish to use.
- *message*: The commit message to use when uploading your documentation.
- *force*: Force the push to the repository.
- *ignore_version*: Ignore check that build is not being deployed with an old version.
- *modules*: One or more modules to render reference documentation for
"""
directory = directory if directory else os.getcwd()
project_config = project_configuration(directory, config_file, modules)
with render.documentation_in_temp_folder(project_config):
conf = render._mkdocs_config(project_config["mkdocs"])
conf.config_file_path = directory
mkdocs.commands.gh_deploy.gh_deploy(conf,
message=message,
force=force,
ignore_version=ignore_version)
print(logo.ascii_art)
print("Documentation successfully generated and pushed!")
def reloader(): # pragma: no cover
sources_old = sources_folder + ".old"
docs_old = docs_folder + ".old"
with render.documentation_in_temp_folder(project_config) as (
sources_new, docs_new):
# cause as little churn as possible to the server watchers
os.rename(sources_folder, sources_old)
os.rename(sources_new, sources_folder)
os.rename(sources_old, sources_new)
os.rename(docs_folder, docs_old)
os.rename(docs_new, docs_folder)
os.rename(docs_old, docs_new)
def server(
directory: str = "",
config_file: str = "pyproject.toml",
open_browser: bool = False,
port: int = None,
host: str = None,
modules: list = None,
) -> None:
"""Runs a development webserver enabling you to browse documentation locally.
- *directory*: The root folder of your project.
- *config_file*: The [TOML](https://github.com/toml-lang/toml#toml) formatted
config file you wish to use.
- *open_browser*: If true a browser will be opened pointing at the documentation server
- *port*: The port to expose your documentation on (defaults to: `8000`)
- *host*: The host to expose your documentation on (defaults to `"127.0.0.1"`)
- *modules*: One or more modules to render reference documentation for
"""
directory = directory if directory else os.getcwd()
api = hug.API("Doc Server")
project_config = project_configuration(directory,
config_file,
modules=modules)
host = host or project_config["host"]
port = port or project_config["port"]
with render.documentation_in_temp_folder(project_config) as doc_folder:
@hug.static("/", api=api)
def my_static_dirs(): # pragma: no cover
return (doc_folder, )
@hug.startup(api=api)
def custom_startup(*args, **kwargs): # pragma: no cover
print(logo.ascii_art)
if open_browser:
webbrowser.open_new(f"http://{host}:{port}")
api.http.serve(host=host,
port=port,
no_documentation=True,
display_intro=False)
def server(
directory: str = "",
config_file: str = "pyproject.toml",
open_browser: bool = False,
port: int = None,
host: str = None,
modules: list = None,
reload: bool = False,
) -> None:
"""Runs a development webserver enabling you to browse documentation locally.
- *directory*: The root folder of your project.
- *config_file*: The [TOML](https://github.com/toml-lang/toml#toml) formatted
config file you wish to use.
- *open_browser*: If true a browser will be opened pointing at the documentation server
- *port*: The port to expose your documentation on (defaults to: `8000`)
- *host*: The host to expose your documentation on (defaults to `"127.0.0.1"`)
- *modules*: One or more modules to render reference documentation for
- *reload*: If true the server will live load any changes
"""
directory = directory if directory else os.getcwd()
project_config = project_configuration(directory,
config_file,
modules=modules)
host = host or project_config["host"]
port = port or project_config["port"]
with render.documentation_in_temp_folder(project_config) as (
sources_folder, docs_folder):
print(logo.ascii_art)
live_server = Server()
if reload:
def reloader(): # pragma: no cover
sources_old = sources_folder + ".old"
docs_old = docs_folder + ".old"
with render.documentation_in_temp_folder(project_config) as (
sources_new, docs_new):
# cause as little churn as possible to the server watchers
os.rename(sources_folder, sources_old)
os.rename(sources_new, sources_folder)
os.rename(sources_old, sources_new)
os.rename(docs_folder, docs_old)
os.rename(docs_new, docs_folder)
os.rename(docs_old, docs_new)
# all directories that feed documentation_in_temp_folder
watch_dirs = set((
project_config["directory"],
project_config["docs_dir"],
*project_config["extra_dirs"],
))
if "docs_dir" in project_config["mkdocs"]:
watch_dirs.add(project_config["mkdocs"]["docs_dir"])
if "site_dir" in project_config["mkdocs"]:
watch_dirs.add(project_config["mkdocs"]["site_dir"])
for watch_dir in watch_dirs.difference(
set((sources_folder, docs_folder))):
live_server.watch(watch_dir, reloader)
if open_browser:
webbrowser.open_new(f"http://{host}:{port}")
live_server.serve(root=docs_folder,
host=host,
port=port,
restart_delay=0)