Add releasing packages documentation #1689

BryceGattis · 2024-03-17T17:00:46Z

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

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

…eally documented Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

BryceGattis · 2024-03-17T17:03:37Z

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 · 2024-03-17T17:04:57Z

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 · 2024-03-17T17:09:42Z

@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'), 
        
           }

docs/README.md

docs/source/index.rst

docs/source/releasing_packages.rst

JeanChristopheMorinPerso · 2024-03-17T18:47:02Z

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

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

codecov · 2024-03-18T12:58:02Z

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.

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

…ing_packages_documentation

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

docs/source/releasing_packages.rst

Signed-off-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com>

JeanChristopheMorinPerso

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

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

BryceGattis added 2 commits March 17, 2024 11:36

Improve README for doc building

64f5ade

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

Add new releasing packages doc page since releasing packages wasn't r…

3b315c4

…eally documented Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

BryceGattis requested a review from a team as a code owner March 17, 2024 17:00

JeanChristopheMorinPerso reviewed Mar 17, 2024

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

docs/source/index.rst Outdated Show resolved Hide resolved

docs/source/releasing_packages.rst Outdated Show resolved Hide resolved

JeanChristopheMorinPerso added the documentation label Mar 17, 2024

Add new hyperlink in rezconfig.py

d456a6e

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

BryceGattis and others added 4 commits March 18, 2024 08:01

Fixup GNU Make requirements info

575881c

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

Move releasing_packages under General tab

e5416f5

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

Merge branch 'AcademySoftwareFoundation:main' into feature/add_releas…

b67cb83

…ing_packages_documentation

Add section on when to release vs build

df85270

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

JeanChristopheMorinPerso added this to the Next milestone Mar 26, 2024

JeanChristopheMorinPerso reviewed Mar 29, 2024

View reviewed changes

docs/source/releasing_packages.rst Outdated Show resolved Hide resolved

docs/source/releasing_packages.rst Outdated Show resolved Hide resolved

docs/source/releasing_packages.rst Outdated Show resolved Hide resolved

Apply suggestions from code review

4ec22b7

Signed-off-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com>

JeanChristopheMorinPerso approved these changes Mar 29, 2024

View reviewed changes

JeanChristopheMorinPerso merged commit 1624f4f into AcademySoftwareFoundation:main Mar 29, 2024
53 checks passed

BryceGattis mentioned this pull request Apr 9, 2024

Document plugin settings #1713

Open

BryceGattis mentioned this pull request May 8, 2024

Migrate plugin type settings to plugin rez configs #1746

Merged

Pixel-Minions added a commit to Pixel-Minions/rez that referenced this pull request Sep 26, 2024

Add releasing packages documentation (AcademySoftwareFoundation#1689)

ccd8241

Signed-off-by: Bryce Gattis <brycegattis@yahoo.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add releasing packages documentation #1689

Add releasing packages documentation #1689

BryceGattis commented Mar 17, 2024

BryceGattis commented Mar 17, 2024

BryceGattis commented Mar 17, 2024 •

edited

Loading

BryceGattis commented Mar 17, 2024

JeanChristopheMorinPerso left a comment

JeanChristopheMorinPerso commented Mar 17, 2024

codecov bot commented Mar 18, 2024 •

edited

Loading

JeanChristopheMorinPerso left a comment

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

Add releasing packages documentation #1689

Add releasing packages documentation #1689

Conversation

BryceGattis commented Mar 17, 2024

BryceGattis commented Mar 17, 2024

BryceGattis commented Mar 17, 2024 • edited Loading

BryceGattis commented Mar 17, 2024

JeanChristopheMorinPerso left a comment

Choose a reason for hiding this comment

JeanChristopheMorinPerso commented Mar 17, 2024

codecov bot commented Mar 18, 2024 • edited Loading

Codecov Report

JeanChristopheMorinPerso left a comment

Choose a reason for hiding this comment

BryceGattis commented Mar 17, 2024 •

edited

Loading

codecov bot commented Mar 18, 2024 •

edited

Loading