From 67c5a76f2027c649657933425a901dc93576973a Mon Sep 17 00:00:00 2001 From: Arthur Hanson Date: Mon, 11 Sep 2023 13:04:20 -0700 Subject: [PATCH] Fix docs (#581) --- .readthedocs.yaml | 30 ++------ docs/Makefile | 10 +-- docs/conf.py | 160 ++++++------------------------------------ docs/index.rst | 3 +- docs/requirements.txt | 4 ++ pynetbox/__init__.py | 4 +- 6 files changed, 41 insertions(+), 170 deletions(-) create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index b468076c..5e6ee28d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,35 +1,15 @@ -# Read the Docs configuration file for Sphinx projects -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required version: 2 -# Set the OS, Python version and other tools you might need build: os: ubuntu-22.04 tools: python: "3.11" - # You can also specify other tool versions: - # nodejs: "20" - # rust: "1.70" - # golang: "1.20" -# Build documentation in the "docs/" directory with Sphinx +# Build from the docs/ directory with Sphinx sphinx: configuration: docs/conf.py - # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs - # builder: "dirhtml" - # Fail on all warnings to avoid broken references - # fail_on_warning: true - -# Optionally build your docs in additional formats such as PDF and ePub -# formats: -# - pdf -# - epub -# Optional but recommended, declare the Python requirements required -# to build your documentation -# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +# Explicitly set the version of Python and its requirements +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile index c3588be3..d4bb2cbb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,10 +1,10 @@ # Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = pynetbox +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index 036f855b..1d84f0ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,158 +1,44 @@ -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# pynetbox documentation build configuration file, created by -# sphinx-quickstart on Thu Apr 6 22:31:03 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# 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 -from importlib.metadata import metadata +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html -sys.path.insert(0, os.path.abspath("../")) +from importlib.metadata import version +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -# -- General configuration ------------------------------------------------ +project = 'pynetbox' +copyright = '2023, NetBox' +author = 'Abhimanyu Saharan' +release = 'MIT' -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = ["sphinx.ext.autodoc"] -# Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +exclude_patterns = ["_build"] # The master toctree document. master_doc = "index" -# General information about the project. -project = "pynetbox" -copyright = "2017, DigitalOcean" -author = "Zach Moody" +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" + +htmlhelp_basename = "pynetboxdoc" + +pygments_style = "sphinx" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # The full version, including alpha/beta/rc tags. -release = metadata(__name__).get("Version") +release_version = version("pynetbox") # # The short X.Y version. -version = ".".join(release.split(".")[:2]) - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -# html_theme = 'classic' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - -html_sidebars = { - "**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"] -} - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = "pynetboxdoc" - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, "pynetbox.tex", "pynetbox Documentation", "Zach Moody", "manual"), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "pynetbox", "pynetbox Documentation", [author], 1)] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "pynetbox", - "pynetbox Documentation", - author, - "pynetbox", - "A python library for NetBox.", - "Miscellaneous", - ), -] +version = ".".join(release_version.split(".")[:2]) diff --git a/docs/index.rst b/docs/index.rst index 4db65219..4deeac23 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,10 +6,11 @@ response request IPAM + advanced TL;DR ===== -Instantiate the :py:class:`.Api`. Use the methods available on :py:class:`.Endpoint` to return :py:class:`.Record` objects. +Instantiate the :py:class:`.Api`. Use the methods available on :py:class:`.Endpoint` to return :py:class:`.Record` objects. API === diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..d9539554 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx<8.0.0 +sphinx_rtd_theme<2.0.0 +readthedocs-sphinx-search<0.4.0 +pynetbox diff --git a/pynetbox/__init__.py b/pynetbox/__init__.py index 024701e3..07fcf69a 100644 --- a/pynetbox/__init__.py +++ b/pynetbox/__init__.py @@ -1,6 +1,6 @@ -from importlib.metadata import metadata +from importlib.metadata import version from pynetbox.core.query import RequestError, AllocationError, ContentError from pynetbox.core.api import Api as api -__version__ = metadata(__name__).get("Version") +__version__ = version(__name__)