diff --git a/doc_requirements.txt b/doc_requirements.txt index a28e3ecac..510877332 100644 --- a/doc_requirements.txt +++ b/doc_requirements.txt @@ -1,15 +1,5 @@ -# WARNING: DO NOT EDIT! -# -# This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_rpm' to update this file. -# -# For more info visit https://github.com/pulp/plugin_template --r requirements.txt plantuml -sphinx~=7.1.2 -sphinx-rtd-theme==1.3.0 -sphinxcontrib-jquery +sphinx +sphinx-rtd-theme sphinxcontrib-openapi towncrier -mistune<4.0.0 -Jinja2<3.2 diff --git a/docs/Makefile b/docs/Makefile index 0bf456ece..7b2b358bf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,37 +1,28 @@ -# WARNING: DO NOT EDIT! -# -# This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_rpm' to update this file. -# -# For more info visit https://github.com/pulp/plugin_template # Makefile for Sphinx documentation # -SHELL := /bin/bash # You can set these variables from the command line. -SPHINXOPTS = -W # turn warnings into errors -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build -DIAGRAM_BUILD_DIR = _diagrams -PULP_URL ?= http://localhost:24817 -PULP_API_ROOT ?= /pulp/ - +SPHINXOPTS = -W -n +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build +STATIC_BUILD_DIR = _static +DIAGRAM_BUILD_DIR = _diagrams +DIAGRAM_SOURCE_DIR = diagrams_src +PULP_URL = "http://localhost:24817" # Internal variables. -PULP_V3_API_JSON_URL := ${PULP_URL}${PULP_API_ROOT}api/v3/docs/api.json -PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext diagrams +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" - @echo " diagrams to make diagram images" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @@ -53,40 +44,27 @@ help: clean: -rm -rf $(BUILDDIR)/* - -rm -rf $(DIAGRAM_BUILD_DIR)/* - -install: - python3 -m venv pulpdocs - source pulpdocs/bin/activate && pip install -r ../doc_requirements.txt diagrams: -ifneq ($(wildcard diagrams_src), ) +ifneq ($(wildcard $(DIAGRAM_SOURCE_DIR)), ) mkdir -p $(DIAGRAM_BUILD_DIR) -ifneq ("$(wildcard pulpdocs/bin/activate)","") - source pulpdocs/bin/activate && python3 -m plantuml diagrams_src/*.dot -else python3 -m plantuml diagrams_src/*.dot -endif - mv diagrams_src/*.png $(DIAGRAM_BUILD_DIR)/ + # cp + rm = mv workaround https://pulp.plan.io/issues/4791#note-3 + cp diagrams_src/*.png $(DIAGRAM_BUILD_DIR)/ + rm diagrams_src/*.png else - @echo "Did not find $(DIAGRAM_SOURCE_DIR)." + @echo "Did not find diagrams_src." endif -$(BUILDDIR)/html/api.json: - mkdir -p $(BUILDDIR)/html - curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?plugin=pulp_rpm&include_html=1" - -html: $(BUILDDIR)/html/api.json +html: + mkdir -p $(STATIC_BUILD_DIR) + curl --fail -o $(STATIC_BUILD_DIR)/api.json "$(PULP_URL)/pulp/api/v3/docs/api.json?plugin=pulp_rpm&include_html=1" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: -ifneq ("$(wildcard pulpdocs/bin/activate)","") - source pulpdocs/bin/activate && PULP_CONTENT_ORIGIN=localhost $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml -else - PULP_CONTENT_ORIGIN=localhost $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml -endif + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." @@ -116,17 +94,17 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PulpDocs.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PulpRPMSupport.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PulpDocs.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PulpRPMSupport.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/PulpDocs" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PulpDocs" + @echo "# mkdir -p $$HOME/.local/share/devhelp/PulpRPMSupport" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PulpRPMSupport" @echo "# devhelp" epub: @@ -190,6 +168,3 @@ doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." - -run: - cd $(BUILDDIR) && python -m http.server 8010 diff --git a/docs/_templates/restapi.html b/docs/_templates/restapi.html index d8364a443..ff2abecbd 100644 --- a/docs/_templates/restapi.html +++ b/docs/_templates/restapi.html @@ -1,7 +1,7 @@ - REST API for Pulp 3 rpm Plugin + REST API for Pulp 3 RPM Plugin @@ -18,7 +18,7 @@ - + diff --git a/docs/changes.rst b/docs/changes.rst index 621110760..b2a06bee7 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -1,4 +1,4 @@ -.. _pulp_rpm-changes: +.. _pulp-rpm-changes: .. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py old mode 100755 new mode 100644 index 45b5e62c1..b7983db1d --- a/docs/conf.py +++ b/docs/conf.py @@ -1,9 +1,8 @@ -# WARNING: DO NOT EDIT! +# -*- coding: utf-8 -*- # -# This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_rpm' to update this file. +# Pulp RPM Support documentation build configuration file, created by +# sphinx-quickstart on Tue Nov 27 11:32:17 2012. # -# For more info visit https://github.com/pulp/plugin_template # 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 @@ -12,29 +11,25 @@ # 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. +#sys.path.insert(0, os.path.abspath('.')) + + import os import sys -from datetime import date +sys.path.insert(0, os.path.abspath('..')) # noqa + +import pulp_rpm try: import sphinx_rtd_theme except ImportError: sphinx_rtd_theme = False -# 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. -sys.path.insert(0, os.path.abspath('./extensions')) # noqa - -sys.path.insert(0, os.path.abspath('..')) # noqa -# Set environment variable so Sphinx can bootstrap the Django app -os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings" - -import django -django.setup() - # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -42,14 +37,7 @@ # 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.extlinks', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon', - 'sphinxcontrib.openapi', - 'sphinxcontrib.jquery', -] +extensions = ['sphinx.ext.extlinks'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -60,14 +48,12 @@ # The encoding of source files. #source_encoding = 'utf-8-sig' -# The top level toctree document. +# The master toctree document. master_doc = 'index' # General information about the project. -project = u'Pulp rpm Support' - -# Set copyright to current year -copyright = u'2012-{0}, Pulp Team'.format(date.today().year) +project = u'Pulp RPM Support' +copyright = u'2012-2019, Pulp Team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -90,7 +76,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', 'pulpdocs'] +exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -112,12 +98,6 @@ # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] -# Set autodoc default options -# Document all module/class/etc members, even if they have no docstring. -# Show class inheritance, and group class members together by type (attr, method, etc) -autodoc_default_flags = ['members', 'undoc-members'] -autodoc_member_order = 'groupwise' -autoclass_content = 'both' # -- Options for HTML output --------------------------------------------------- @@ -152,7 +132,7 @@ # 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_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -196,7 +176,7 @@ #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'PulpDocs' +htmlhelp_basename = 'PulpRPMSupportdoc' # -- Options for LaTeX output -------------------------------------------------- @@ -212,6 +192,13 @@ #'preamble': '', } +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'PulpRPMSupport.tex', u'Pulp RPM Support Documentation', + u'Pulp Team', 'manual'), +] + # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None @@ -232,9 +219,31 @@ # If false, no module index is generated. #latex_domain_indices = True + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'pulprpmsupport', u'Pulp RPM Support Documentation', + [u'Pulp Team'], 1) +] + # If true, show URL addresses after external links. #man_show_urls = False + +# -- 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 = [ + ('index', 'PulpRPMSupport', u'Pulp RPM Support Documentation', + u'Pulp Team', 'PulpRPMSupport', 'One line description of project.', + 'Miscellaneous'), +] + # Documents to append as an appendix to all manuals. #texinfo_appendices = [] @@ -243,43 +252,3 @@ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' - -extlinks = { - 'github': ('https://github.com/pulp/pulpcore/issues/%s', '#%s'), - 'redmine': ('https://pulp.plan.io/issues/%s', '#%s'), -} - -# napoleon uses .. attribute by default, but :ivar: is more succinct and looks better, -# particularly on classes with a lot of attributes, like django models and related objects -napoleon_use_ivar = True - -# set primary domain to python so we don't have to include :py: in xref links -default_domain = 'py' - -from sphinx.domains.python import PythonDomain - -# Adapted from: -# https://github.com/sphinx-doc/sphinx/issues/3866#issuecomment-366014346 -# Required because pulpcore.app and pulpcore.plugin have the same class names -# and Sphinx can't figure out which it should be using. This code defaults to -# pulpcore.app -class MyPythonDomain(PythonDomain): - def find_obj(self, env, modname, classname, name, type, searchmode=0): - """Ensures an object always resolves to the desired module if defined there.""" - orig_matches = PythonDomain.find_obj(self, env, modname, classname, name, type, searchmode) - matches = [] - for match in orig_matches: - match_name = match[0] - desired_name = "pulpcore.app.models." + name.strip('.') - if match_name == desired_name: - matches.append(match) - break - if matches: - return matches - else: - return orig_matches - - -def setup(sphinx): - """Use MyPythonDomain in place of PythonDomain""" - sphinx.add_domain(MyPythonDomain, override=True) diff --git a/docs/static/.gitkeep b/docs/static/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/template_gitref b/docs/template_gitref deleted file mode 100644 index e07643162..000000000 --- a/docs/template_gitref +++ /dev/null @@ -1 +0,0 @@ -2021.08.26-248-g4bfc3e1