Add releasing packages documentation

[BryceGattis]

Added a new page for releasing packages since there doesn't seem to be any for the rez-release workflow yet.

[BryceGattis]

I don't believe the release_vcs configuration setting is documented at all yet on the "configuring Rez" page. Can someone sanity check me here...?

[BryceGattis]

Once the release_vcs setting is documented, I think it'd be nice to split out package build and package release configuration settings into 2 different sections, rather than just the single section as it is now for clarity.

[BryceGattis]

@JeanChristopheMorinPerso Also, is it possible to actually get hyper links to source code? There's one reference that doesn't have a hyper link related to this PR that could be nice to get working. It's the rezplugins/release_hook at the bottom of the paragraph.

[JeanChristopheMorinPerso]

Thanks! I added some comments.

is it possible to actually get hyper links to source code?

Yes, see

rez/docs/source/configuring_rez.rst

Line 6 in 1d18bc2

documentation for every setting, can be found :gh-rez:`src/rez/rezconfig.py`.

This is configured in

rez/docs/source/conf.py

Lines 102 to 104 in 1d18bc2

	extlinks = {
	'gh-rez': ('https://github.com/AcademySoftwareFoundation/rez/blob/master/%s', '%s'),
	}

[JeanChristopheMorinPerso]

I don't believe the release_vcs configuration setting is documented at all yet on the "configuring Rez" page. Can someone sanity check me here...?

Plugins settings are not yet documented. Doing so would require some work since settings are right now documented in multiple places. For example, technically the canonical source should be in https://github.com/AcademySoftwareFoundation/rez/blob/main/src/rezplugins/release_vcs/rezconfig, but it only documents and sets one default value and the rest is in https://github.com/AcademySoftwareFoundation/rez/blob/main/src/rez/rezconfig.py#L1201-L1242.

At the very least, if you want to have plugins shown as a section in https://rez.readthedocs.io/en/stable/configuring_rez.html#configuration-settings, you would have to remove this empty line. I didn't do it because the result is ugly and not accurate.

If you are curious, the code that generates https://rez.readthedocs.io/en/stable/configuring_rez.html#configuration-settings is at

rez/docs/rez_sphinxext.py

Lines 19 to 173 in 1d18bc2

	def convert_rez_config_to_rst() -> list[str]:
	with open(rez.rezconfig.__file__) as fd:
	txt = fd.read()
	lines = txt.split('\n')
	start = None
	end = None
	for i, line in enumerate(lines):
	if "__DOC_START__" in line:
	start = i
	elif "__DOC_END__" in line:
	end = i
	lines = lines[start:end + 1]
	assign_regex = re.compile("^([a-z0-9_]+) =")
	settings = {}
	section_header = re.compile(r"^\#{10,}")
	section_title = None
	section_description = None
	end_of_section = 0
	# parse out settings sections, settings and their comment
	for i, line in enumerate(lines):
	if section_header.match(line) and i != end_of_section:
	section_title = lines[i + 1].split('#', 1)[-1].strip()
	section_description = ''
	description_linenumber = i + 2
	end_of_section = description_linenumber
	while not section_header.match(lines[description_linenumber]):
	section_description += lines[description_linenumber].split('#', 1)[-1].strip() + '\n'
	description_linenumber += 1
	end_of_section = description_linenumber
	m = assign_regex.match(line)
	if not m:
	continue
	start_defn = i
	end_defn = i
	while lines[end_defn].strip() and not lines[end_defn].startswith('#'):
	end_defn += 1
	value_lines = lines[start_defn:end_defn]
	value_lines[0] = value_lines[0].split("=")[-1].strip()
	end_comment = i
	while not lines[end_comment].startswith('#'):
	end_comment -= 1
	start_comment = end_comment
	while lines[start_comment].startswith('#'):
	start_comment -= 1
	start_comment += 1
	comments = lines[start_comment:end_comment + 1]
	comment_lines = [x[2:] for x in comments] # drop leading '# '
	varname = m.groups()[0]
	if section_title in settings:
	settings[section_title]['settings'][varname] = (value_lines, comment_lines)
	else:
	settings[section_title] = {
	'desc': section_description,
	'settings': {varname: (value_lines, comment_lines)}
	}
	# generate rst text
	# rst = ['.. currentmodule:: config']
	rst = []
	for section in settings:
	rst.append('')
	rst.append(".. _config-{}:".format(section.replace(' ', '-').lower()))
	rst.append("")
	rst.append(section)
	rst.append("-" * len(section))
	rst.append('')
	# This seems benign (storing each line individually), but it's actually extremelly
	# important. The docutils ViewList class absolutely requires to have only one line per
	# entry. If we don't do that, the docutils parser won't parse the sublines,
	# and we'll get "garbage" (ie unformatted lines) in the output.
	for line in settings[section]['desc'].strip().split('\n'):
	rst.append(line)
	rst.append('')
	for varname, (value_lines, comment_lines) in sorted(settings[section]['settings'].items()):
	rst.append(".. py:data:: {0}".format(varname))
	if len(value_lines) == 1:
	rst.append(" :value: {0}".format(value_lines[0]))
	else:
	rst.append('')
	rst.append(' Default:')
	rst.append('')
	rst.append(' .. code-block:: python')
	rst.append('')
	for line in value_lines:
	rst.append(f' {line}')
	rst.append('')
	for line in comment_lines:
	rst.append(f' {line}')
	rst.append('')
	envvar = f'REZ_{varname.upper()}'
	rst.append(f' .. envvar:: {envvar}')
	rst.append('')
	rst.append(f' The ``{envvar}`` environment variable can also be used to configure this.')
	rst.append('')
	return rst
	# Inspired by https://github.com/pypa/pip/blob/4a79e65cb6aac84505ad92d272a29f0c3c1aedce/docs/pip_sphinxext.py
	# https://stackoverflow.com/a/44084890
	class RezConfigDirective(sphinx.util.docutils.SphinxDirective):
	"""
	Special rez-config directive. This is quite similar to "autodoc" in some ways.
	"""
	required_arguments = 0
	optional_arguments = 0
	def run(self) -> list[docutils.nodes.Node]:
	# Create the node.
	node = docutils.nodes.section()
	node.document = self.state.document
	rst = docutils.statemachine.ViewList()
	# Get the configuration settings as reStructuredText text.
	configLines = convert_rez_config_to_rst()
	# Add rezconfig as a dependency to the current document. The document
	# will be rebuilt if rezconfig changes.
	self.env.note_dependency(rez.rezconfig.__file__)
	self.env.note_dependency(__file__)
	path, lineNumber = self.get_source_info()
	# Add each line to the view list.
	for index, line in enumerate(configLines):
	# Note to future people that will look at this.
	# "line" has to be a single line! It can't be a line like "this\nthat".
	rst.append(line, path, lineNumber+index)
	# Finally, convert the rst into the appropriate docutils/sphinx nodes.
	sphinx.util.nodes.nested_parse_with_titles(self.state, rst, node)
	# Return the generated nodes.
	return node.children

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 58.25%. Comparing base (c216f9d) to head (4ec22b7).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1689      +/-   ##
==========================================
+ Coverage   58.05%   58.25%   +0.20%     
==========================================
  Files         126      126              
  Lines       17035    17157     +122     
  Branches     3490     3504      +14     
==========================================
+ Hits         9889     9995     +106     
- Misses       6482     6496      +14     
- Partials      664      666       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[JeanChristopheMorinPerso]

Thanks again @BryceGattis for your continuous efforts at improving our docs!