From 385302a4876a651e1a3511c3738eb45f0538a2d5 Mon Sep 17 00:00:00 2001 From: Daniel Mach Date: Fri, 21 Jan 2022 13:45:06 +0100 Subject: [PATCH 1/5] Update Sphinx configuration --- docs/Makefile | 20 ++++ docs/conf.py | 289 +++++--------------------------------------------- 2 files changed, 47 insertions(+), 262 deletions(-) create mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# 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 + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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) diff --git a/docs/conf.py b/docs/conf.py index a3c582ab..608b636e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,35 +1,28 @@ -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# osc documentation build configuration file, created by -# sphinx-quickstart on Sun Jan 24 13:06:29 2016. -# -# 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. - -import sys -import os -import shlex - - -# top level dir (one above this file) -topdir = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..')) +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# -- Path setup -------------------------------------------------------------- # 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, topdir) +# +import os +import sys +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")) -# -- General configuration ------------------------------------------------ -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# -- Project information ----------------------------------------------------- + +project = 'osc' +copyright = 'Contributors to the osc project' +author = 'see the AUTHORS list' + + +# -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -44,255 +37,27 @@ extensions = [ # 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' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'osc' -copyright = u'2016, see authors list' -author = u'see authors list' - -# 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 short X.Y version. -version = '1.2.3' -# The full version, including alpha/beta/rc tags. -release = '4.5.6' - -# 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 - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +# A string of reStructuredText that will be included at the end of every +# source file that is read. This is a possible place to add substitutions +# that should be available in every file. +rst_epilog = """ +.. |obs| replace:: open build service +""" -# -- Options for HTML output ---------------------------------------------- +# -- 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 = 'alabaster' -# 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 themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - # 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'oscdoc' - -# -- 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, 'osc.tex', u'osc Documentation', - u'see authors list', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# 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 = [ - (master_doc, 'osc', u'osc Documentation', - [author], 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 = [ - (master_doc, 'osc', u'osc Documentation', - author, 'osc', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - -rst_epilog = """ -.. |obs| replace:: open build service -""" From 6ccd1bc2cdc0037e90f5e8a01fb0581e800e44aa Mon Sep 17 00:00:00 2001 From: Daniel Mach Date: Fri, 21 Jan 2022 13:49:17 +0100 Subject: [PATCH 2/5] Rename 'docs' directory to 'doc' This seems to be a more common directory name in the projects. --- {docs => doc}/Makefile | 0 {docs => doc}/_static/.keepme | 0 {docs => doc}/api/modules.rst | 0 {docs => doc}/api/osc.OscConfigParser.rst | 0 {docs => doc}/api/osc.build.rst | 0 {docs => doc}/api/osc.conf.rst | 0 {docs => doc}/api/osc.core.rst | 0 {docs => doc}/api/osc.credentials.rst | 0 {docs => doc}/api/osc.util.rst | 0 {docs => doc}/api/tutorial.rst | 0 {docs => doc}/conf.py | 0 {docs => doc}/index.rst | 0 12 files changed, 0 insertions(+), 0 deletions(-) rename {docs => doc}/Makefile (100%) rename {docs => doc}/_static/.keepme (100%) rename {docs => doc}/api/modules.rst (100%) rename {docs => doc}/api/osc.OscConfigParser.rst (100%) rename {docs => doc}/api/osc.build.rst (100%) rename {docs => doc}/api/osc.conf.rst (100%) rename {docs => doc}/api/osc.core.rst (100%) rename {docs => doc}/api/osc.credentials.rst (100%) rename {docs => doc}/api/osc.util.rst (100%) rename {docs => doc}/api/tutorial.rst (100%) rename {docs => doc}/conf.py (100%) rename {docs => doc}/index.rst (100%) diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile diff --git a/docs/_static/.keepme b/doc/_static/.keepme similarity index 100% rename from docs/_static/.keepme rename to doc/_static/.keepme diff --git a/docs/api/modules.rst b/doc/api/modules.rst similarity index 100% rename from docs/api/modules.rst rename to doc/api/modules.rst diff --git a/docs/api/osc.OscConfigParser.rst b/doc/api/osc.OscConfigParser.rst similarity index 100% rename from docs/api/osc.OscConfigParser.rst rename to doc/api/osc.OscConfigParser.rst diff --git a/docs/api/osc.build.rst b/doc/api/osc.build.rst similarity index 100% rename from docs/api/osc.build.rst rename to doc/api/osc.build.rst diff --git a/docs/api/osc.conf.rst b/doc/api/osc.conf.rst similarity index 100% rename from docs/api/osc.conf.rst rename to doc/api/osc.conf.rst diff --git a/docs/api/osc.core.rst b/doc/api/osc.core.rst similarity index 100% rename from docs/api/osc.core.rst rename to doc/api/osc.core.rst diff --git a/docs/api/osc.credentials.rst b/doc/api/osc.credentials.rst similarity index 100% rename from docs/api/osc.credentials.rst rename to doc/api/osc.credentials.rst diff --git a/docs/api/osc.util.rst b/doc/api/osc.util.rst similarity index 100% rename from docs/api/osc.util.rst rename to doc/api/osc.util.rst diff --git a/docs/api/tutorial.rst b/doc/api/tutorial.rst similarity index 100% rename from docs/api/tutorial.rst rename to doc/api/tutorial.rst diff --git a/docs/conf.py b/doc/conf.py similarity index 100% rename from docs/conf.py rename to doc/conf.py diff --git a/docs/index.rst b/doc/index.rst similarity index 100% rename from docs/index.rst rename to doc/index.rst From a06c30a96386f7177a98d47290973180ead90a61 Mon Sep 17 00:00:00 2001 From: Daniel Mach Date: Fri, 21 Jan 2022 13:53:44 +0100 Subject: [PATCH 3/5] Create './setup.py build_doc' cmd according to the Sphinx best practices Renaming 'build_docs' to 'build_doc' is probably ok as the command was broken and couldn't be used by anyone. --- setup.py | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/setup.py b/setup.py index e8f68063..65c949db 100755 --- a/setup.py +++ b/setup.py @@ -6,6 +6,9 @@ from distutils.command import build, install_data import gzip import os.path +import sphinx.setup_command + + import setuptools import osc.core @@ -36,29 +39,6 @@ class build_osc(build.build, object): self.build_man_page() -# Support for documentation (sphinx) -class build_docs(distutils.core.Command): - description = 'builds documentation using sphinx' - user_options = [] - - def initialize_options(self): - self.built_docs = None - - def finalize_options(self): - self.set_undefined_options('build', ('build_base', 'built_docs')) - - def run(self): - # metadata contains information supplied in setup() - metadata = self.distribution.metadata - # package_dir may be None, in that case use the current directory. - src_dir = (self.distribution.package_dir or {'': ''})[''] - src_dir = os.path.join(os.getcwd(), src_dir) - import sphinx - sphinx.main(['runme', - '-D', 'version=%s' % metadata.get_version(), - os.path.join('docs', ), os.path.join(self.built_docs, 'docs')]) - - # take a potential build-base option into account (for instance, if osc is # build and installed like this: # python setup.py build --build-base= ... install ...) @@ -128,11 +108,10 @@ setuptools.setup( "Topic :: System :: Archiving :: Packaging", ], - # Override certain command classes with our own ones cmdclass={ 'build': build_osc, - 'build_docs': build_docs, + 'build_doc': sphinx.setup_command.BuildDoc, 'install_data': install_data }, ) From 3ca3c804d141d4dbd5557a20e30ce940ef46f8e0 Mon Sep 17 00:00:00 2001 From: Daniel Mach Date: Mon, 24 Jan 2022 08:40:23 +0100 Subject: [PATCH 4/5] Switch html docs theme to RTD as it's easier to read --- doc/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 608b636e..a5dfe4f9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -55,7 +55,8 @@ rst_epilog = """ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +# html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # 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, From 13852979782076c91751e335186b85d795e794ee Mon Sep 17 00:00:00 2001 From: Daniel Mach Date: Mon, 24 Jan 2022 08:57:53 +0100 Subject: [PATCH 5/5] Fix several issues in HTML doc rendering, improve output --- doc/api/osc.OscConfigParser.rst | 2 +- doc/api/osc.build.rst | 2 +- doc/api/osc.credentials.rst | 2 +- osc/OscConfigParser.py | 8 +- osc/build.py | 11 ++- osc/conf.py | 12 +-- osc/core.py | 126 +++++++++++++++++--------------- osc/util/packagequery.py | 2 +- osc/util/repodata.py | 19 +++-- 9 files changed, 100 insertions(+), 84 deletions(-) diff --git a/doc/api/osc.OscConfigParser.rst b/doc/api/osc.OscConfigParser.rst index 3231d8d3..a88942fa 100644 --- a/doc/api/osc.OscConfigParser.rst +++ b/doc/api/osc.OscConfigParser.rst @@ -1,7 +1,7 @@ .. py:module:: osc.OscConfigParser OscConfigParser -==== +=============== This is the osc config parser. diff --git a/doc/api/osc.build.rst b/doc/api/osc.build.rst index ca80847a..e5e41899 100644 --- a/doc/api/osc.build.rst +++ b/doc/api/osc.build.rst @@ -1,7 +1,7 @@ .. py:module:: osc.build build -==== +===== This is the osc build module to talk to the build script. diff --git a/doc/api/osc.credentials.rst b/doc/api/osc.credentials.rst index 03218c52..290ab9b4 100644 --- a/doc/api/osc.credentials.rst +++ b/doc/api/osc.credentials.rst @@ -1,7 +1,7 @@ .. py:module:: osc.credentials credentials -==== +=========== This is the osc credentials module. diff --git a/osc/OscConfigParser.py b/osc/OscConfigParser.py index 8b0a9f43..a36284f8 100644 --- a/osc/OscConfigParser.py +++ b/osc/OscConfigParser.py @@ -173,11 +173,13 @@ class CommentLine(Line): class OptionLine(Line): """ - This class represents an option. The class' "name" attribute is used + This class represents an option. The class' ``name`` attribute is used to store the option's name and the "value" attribute contains the option's - value. The "frmt" attribute preserves the format which was used in the configuration + value. The ``frmt`` attribute preserves the format which was used in the configuration file. - Example: + + Example:: + optionx:value => self.frmt = '%s:%s' optiony=value;some_comment diff --git a/osc/build.py b/osc/build.py index ff3d3155..16471cae 100644 --- a/osc/build.py +++ b/osc/build.py @@ -301,10 +301,12 @@ class Pac: def get_preinstall_image(apiurl, arch, cache_dir, img_info, offline=False): """ Searches preinstall image according to build info and downloads it to cache - (unless offline is set to True (default: False)). + (unless offline is set to ``True`` (default: ``False``)). Returns preinstall image path, source and list of image binaries, which can be used to create rpmlist. - NOTE: preinstall image can be used only for new build roots! + + .. note:: + preinstall image can be used only for new build roots! """ imagefile = '' imagesource = '' @@ -436,8 +438,9 @@ def get_built_files(pacdir, buildtype): def get_repo(path): """Walks up path looking for any repodata directories. - @param path path to a directory - @return str path to repository directory containing repodata directory + :param path: path to a directory + :return: path to repository directory containing repodata directory + :rtype: str """ oldDirectory = None currentDirectory = os.path.abspath(path) diff --git a/osc/conf.py b/osc/conf.py index e5a08bbd..5ccebaf9 100644 --- a/osc/conf.py +++ b/osc/conf.py @@ -442,7 +442,7 @@ def urljoin(scheme, apisrv, path=''): def is_known_apiurl(url): - """returns true if url is a known apiurl""" + """returns ``True`` if url is a known apiurl""" apiurl = urljoin(*parse_apisrv_url(None, url)) return apiurl in config['api_host_options'] @@ -464,8 +464,8 @@ def extract_known_apiurl(url): def get_apiurl_api_host_options(apiurl): """ - Returns all apihost specific options for the given apiurl, None if - no such specific optiosn exist. + Returns all apihost specific options for the given apiurl, ``None`` if + no such specific options exist. """ # FIXME: in A Better World (tm) there was a config object which # knows this instead of having to extract it from a url where it @@ -729,9 +729,9 @@ def config_set_option(section, opt, val=None, delete=False, update=True, creds_m """ Sets a config option. If val is not specified the current/default value is returned. If val is specified, opt is set to val and the new value is returned. - If an option was modified get_config is called with **kwargs unless update is set - to False (override_conffile defaults to config['conffile']). - If val is not specified and delete is True then the option is removed from the + If an option was modified get_config is called with ``**kwargs`` unless update is set + to ``False`` (``override_conffile`` defaults to ``config['conffile']``). + If val is not specified and delete is ``True`` then the option is removed from the config/reset to the default value. """ cp = get_configParser(config['conffile']) diff --git a/osc/core.py b/osc/core.py index 90cd316c..b4a19413 100644 --- a/osc/core.py +++ b/osc/core.py @@ -296,7 +296,7 @@ class Serviceinfo: self.package = None def read(self, serviceinfo_node, append=False): - """read in the source services element passed as + """read in the source services ```` element passed as elementtree node. """ def error(msg, xml): @@ -509,7 +509,7 @@ class Serviceinfo: return 0 class Linkinfo: - """linkinfo metadata (which is part of the xml representing a directory + """linkinfo metadata (which is part of the xml representing a directory) """ def __init__(self): """creates an empty linkinfo instance""" @@ -523,9 +523,9 @@ class Linkinfo: self.baserev = None def read(self, linkinfo_node): - """read in the linkinfo metadata from the element passed as + """read in the linkinfo metadata from the ```` element passed as elementtree node. - If the passed element is None, the method does nothing. + If the passed element is ``None``, the method does nothing. """ if linkinfo_node == None: return @@ -539,19 +539,19 @@ class Linkinfo: self.baserev = linkinfo_node.get('baserev') def islink(self): - """returns True if the linkinfo is not empty, otherwise False""" + """:return: ``True`` if the linkinfo is not empty, otherwise ``False``""" if self.xsrcmd5 or self.lsrcmd5 or self.error is not None: return True return False def isexpanded(self): - """returns True if the package is an expanded link""" + """:return: ``True`` if the package is an expanded link""" if self.lsrcmd5 and not self.xsrcmd5: return True return False def haserror(self): - """returns True if the link is in error state (could not be applied)""" + """:return: ``True`` if the link is in error state (could not be applied)""" if self.error: return True return False @@ -1824,12 +1824,12 @@ class Package: def islink(self): """tells us if the package is a link (has 'linkinfo'). A package with linkinfo is a package which links to another package. - Returns True if the package is a link, otherwise False.""" + Returns ``True`` if the package is a link, otherwise ``False``.""" return self.linkinfo.islink() def isexpanded(self): """tells us if the package is a link which is expanded. - Returns True if the package is expanded, otherwise False.""" + Returns ``True`` if the package is expanded, otherwise ``False``.""" return self.linkinfo.isexpanded() def islinkrepair(self): @@ -1856,21 +1856,21 @@ class Package: def haslinkerror(self): """ - Returns True if the link is broken otherwise False. - If the package is not a link it returns False. + Returns ``True`` if the link is broken otherwise ``False``. + If the package is not a link it returns ``False``. """ return self.linkinfo.haserror() def linkerror(self): """ - Returns an error message if the link is broken otherwise None. - If the package is not a link it returns None. + Returns an error message if the link is broken otherwise ``None``. + If the package is not a link it returns ``None``. """ return self.linkinfo.error def hasserviceinfo(self): """ - Returns True, if this package contains services. + Returns ``True``, if this package contains services. """ return self.serviceinfo.lsrcmd5 is not None or self.serviceinfo.xsrcmd5 is not None @@ -1908,24 +1908,22 @@ class Package: def status(self, n): """ - status can be: - - file storefile file present STATUS - exists exists in _files - - x - - 'A' and listed in _to_be_added - x x - 'R' and listed in _to_be_added - x x x ' ' if digest differs: 'M' - and if in conflicts file: 'C' - x - - '?' - - x x 'D' and listed in _to_be_deleted - x x x 'D' and listed in _to_be_deleted (e.g. if deleted file was modified) - x x x 'C' and listed in _in_conflict - x - x 'S' and listed in self.skipped - - - x 'S' and listed in self.skipped - - x x '!' - - - - NOT DEFINED + status can be:: + file storefile file present STATUS + exists exists in _files + x - - 'A' and listed in _to_be_added + x x - 'R' and listed in _to_be_added + x x x ' ' if digest differs: 'M' + and if in conflicts file: 'C' + x - - '?' + - x x 'D' and listed in _to_be_deleted + x x x 'D' and listed in _to_be_deleted (e.g. if deleted file was modified) + x x x 'C' and listed in _in_conflict + x - x 'S' and listed in self.skipped + - - x 'S' and listed in self.skipped + - x x '!' + - - - NOT DEFINED """ known_by_meta = False @@ -2513,29 +2511,29 @@ rev: %s class AbstractState: """ - Base class which represents state-like objects (, ). + Base class which represents state-like objects (````, ````). """ def __init__(self, tag): self.__tag = tag def get_node_attrs(self): - """return attributes for the tag/element""" + """:return: attributes for the tag/element""" raise NotImplementedError() def get_node_name(self): - """return tag/element name""" + """:return: tag/element name""" return self.__tag def get_comment(self): - """return data from tag""" + """:return: data from ```` tag""" raise NotImplementedError() def get_description(self): - """return data from tag""" + """:return: data from ```` tag""" raise NotImplementedError() def to_xml(self): - """serialize object to XML""" + """:return: object serialized to XML""" root = ET.Element(self.get_node_name()) for attr in self.get_node_attrs(): val = getattr(self, attr) @@ -2548,7 +2546,7 @@ class AbstractState: return root def to_str(self): - """return "pretty" XML data""" + """:return: object serialized to pretty-printed XML""" root = self.to_xml() xmlindent(root) return ET.tostring(root, encoding=ET_ENCODING) @@ -2655,11 +2653,15 @@ class RequestState(AbstractState): class Action: """ - Represents a element of a Request. + Represents an ```` element of a Request. This class is quite common so that it can be used for all different - action types. Note: instances only provide attributes for their specific - type. - Examples: + action types. + + .. note:: + Instances only provide attributes for their specific type. + + Examples:: + r = Action('set_bugowner', tgt_project='foo', person_name='buguser') # available attributes: r.type (== 'set_bugowner'), r.tgt_project (== 'foo'), r.tgt_package (== None) r.to_str() -> @@ -2667,7 +2669,7 @@ class Action: - ## + r = Action('delete', tgt_project='foo', tgt_package='bar') # available attributes: r.type (== 'delete'), r.tgt_project (== 'foo'), r.tgt_package (=='bar') r.to_str() -> @@ -2712,13 +2714,18 @@ class Action: """ Serialize object to XML. The xml tag names and attributes are constructed from the instance's attributes. - Example: + + :return: object serialized to XML + + Example:: + self.group_name -> tag name is "group", attribute name is "name" self.src_project -> tag name is "source" (translated via prefix_to_elm dict), attribute name is "project" - Attributes prefixed with "opt_" need a special handling, the resulting xml should - look like this: opt_updatelink -> value. - Attributes which are "None" will be skipped. + + Attributes prefixed with ``opt_`` need a special handling, the resulting xml should + look like this: ``opt_updatelink`` -> ``value``. + Attributes which are ``None`` will be skipped. """ root = ET.Element('action', type=self.type) for i in Action.type_args[self.type]: @@ -2743,7 +2750,7 @@ class Action: return root def to_str(self): - """return "pretty" XML data""" + """:return: object serialized to pretty-printed XML""" root = self.to_xml() xmlindent(root) return ET.tostring(root, encoding=ET_ENCODING) @@ -2778,7 +2785,7 @@ class Action: class Request: - """Represents a request ()""" + """Represents a request (````)""" def __init__(self): self._init_attributes() @@ -2850,7 +2857,7 @@ class Request: return self.creator def to_xml(self): - """serialize object to XML""" + """:return: object serialized to XML""" root = ET.Element('request') if self.reqid is not None: root.set('id', self.reqid) @@ -2875,7 +2882,7 @@ class Request: return root def to_str(self): - """return "pretty" XML data""" + """:return: object serialized to pretty-printed XML""" root = self.to_xml() xmlindent(root) return ET.tostring(root, encoding=ET_ENCODING) @@ -4789,7 +4796,7 @@ def sha256_dgst(file): return s.hexdigest() def binary(s): - """return true if a string is binary data using diff's heuristic""" + """return ``True`` if a string is binary data using diff's heuristic""" if s and bytes('\0', "utf-8") in s[:4096]: return True return False @@ -6739,7 +6746,11 @@ def checkRevision(prj, pac, revision, apiurl=None, meta=False): def build_table(col_num, data = [], headline = [], width=1, csv = False): """ This method builds a simple table. - Example1: build_table(2, ['foo', 'bar', 'suse', 'osc'], ['col1', 'col2'], 2) + + Example:: + + build_table(2, ['foo', 'bar', 'suse', 'osc'], ['col1', 'col2'], 2) + col1 col2 foo bar suse osc @@ -7309,7 +7320,9 @@ def getPrjPacPaths(path): returns the path for a project and a package from path. This is needed if you try to add or delete packages: - Examples: + + Examples:: + osc add pac1/: prj_dir = CWD; pac_dir = pac1 osc add /path/to/pac1: @@ -7814,8 +7827,8 @@ def run_external(filename, *args, **kwargs): def return_external(filename, *args, **kwargs): """Executes the program filename via subprocess.check_output. - *args are additional arguments which are passed to the - program filename. **kwargs specify additional arguments for + ``*args`` are additional arguments which are passed to the + program filename. ``**kwargs`` specify additional arguments for the subprocess.check_output function. if no args are specified the plain filename is passed to subprocess.check_output (this can be used to execute a shell @@ -7823,7 +7836,6 @@ def return_external(filename, *args, **kwargs): to the subprocess.check_output function. Returns the output of the command. - """ if args: cmd = [filename] + list(args) diff --git a/osc/util/packagequery.py b/osc/util/packagequery.py index 93a439b5..456b0f5c 100644 --- a/osc/util/packagequery.py +++ b/osc/util/packagequery.py @@ -26,7 +26,7 @@ class PackageQueries(dict): """Adds package query to dict if it is of the correct architecture and is newer (has a greater version) than the currently assigned package. - @param a PackageQuery + :param query: a PackageQuery """ self.__setitem__(query.name(), query) diff --git a/osc/util/repodata.py b/osc/util/repodata.py index 1cde26db..b11da0ed 100644 --- a/osc/util/repodata.py +++ b/osc/util/repodata.py @@ -31,9 +31,10 @@ OPERATOR_BY_FLAGS = { def primaryPath(directory): """Returns path to the primary repository data file. - @param directory repository directory that contains the repodata subdirectory - @return str path to primary repository data file - @raise IOError if repomd.xml contains no primary location + :param directory: repository directory that contains the repodata subdirectory + :return: path to primary repository data file + :rtype: str + :raise IOError: if repomd.xml contains no primary location """ metaDataPath = os.path.join(directory, "repodata", "repomd.xml") elementTree = ET.parse(metaDataPath) @@ -55,10 +56,9 @@ def queries(directory): """Returns a list of RepoDataQueries constructed from the repodata under the directory. - @param directory path to a repository directory (parent directory of - repodata directory) - @return list of RepoDataQueryResult instances - @raise IOError if repomd.xml contains no primary location + :param directory: path to a repository directory (parent directory of repodata directory) + :return: list of RepoDataQueryResult instances + :raise IOError: if repomd.xml contains no primary location """ path = primaryPath(directory) @@ -99,9 +99,8 @@ class RepoDataQueryResult(osc.util.packagequery.PackageQueryResult): """Creates a RepoDataQueryResult from the a package Element under a metadata Element in a primary.xml file. - @param directory repository directory path. Used to convert relative - paths to full paths. - @param element package Element + :param directory: repository directory path. Used to convert relative paths to full paths. + :param element: package Element """ self.__directory = os.path.abspath(directory) self.__element = element