Implementation:MarketSquare Robotframework browser Inv Version Docs

Document Type

API Doc -- Documents the Invoke tasks for version management, keyword documentation generation, and release notes creation in the robotframework-browser project.

API Summary

Three tasks handle release preparation:

• version -- Updates the version string across 6 files in the project
• docs -- Generates HTML keyword documentation using Robot Framework's libdoc
• release_notes -- Auto-generates release notes from GitHub issues

Source References

File	Lines	Description
tasks.py	L988-1025	version task
tasks.py	L842-883	docs task
tasks.py	L945-972	release_notes task
tasks.py	L1028-1031	_replace_version helper

CLI Usage

# Update version across all files
inv version 19.13.0

# Generate keyword documentation
inv docs

# Generate versioned documentation
inv docs --version 19.13.0

# Print release notes to stdout
inv release-notes

# Write release notes to file
inv release-notes --version 19.13.0 --write

# With GitHub credentials for faster API access
inv release-notes --version 19.13.0 --username myuser --password mytoken --write

Task: version

Signature

@task()
def version(c, version):

Parameters

Parameter	Type	Description
version	str	The version string to set (e.g., "19.13.0")

Source Code

@task()
def version(c, version):
    if not version:
        print("Give version with inv version <version>")
    py_version_file = ROOT_DIR / "Browser" / "version.py"
    py_version_matcher = re.compile("__version__ = .*")
    _replace_version(py_version_file, py_version_matcher, f'__version__ = "{version}"')
    node_version_file = ROOT_DIR / "package.json"
    node_version_matcher = re.compile('"version": ".*"')
    _replace_version(node_version_file, node_version_matcher, f'"version": "{version}"')
    package_lock = ROOT_DIR / "package-lock.json"
    data = json.loads(package_lock.read_text())
    data["version"] = version
    data["packages"][""]["version"] = version
    package_lock.write_text(json.dumps(data, indent=2))
    py_project_toml = ROOT_DIR / "pyproject.toml"
    py_project_toml_matcher = re.compile('version = ".*"')
    _replace_version(
        py_project_toml, py_project_toml_matcher, f'version = "{version}"', 1
    )
    py_project_toml = BROWSER_BATTERIES_DIR / "pyproject.toml"
    _replace_version(
        py_project_toml, py_project_toml_matcher, f'version = "{version}"', 1
    )
    py_project_toml_matcher = re.compile(
        r'dependencies = \["robotframework-browser==.*"\]'
    )
    _replace_version(
        py_project_toml,
        py_project_toml_matcher,
        f'dependencies = ["robotframework-browser=={version}"]',
        1,
    )
    dockerfile = ROOT_DIR / "docker" / "Dockerfile.latest_release"
    docker_version_matcher = re.compile("robotframework-browser==.*")
    _replace_version(
        dockerfile, docker_version_matcher, f"robotframework-browser=={version}"
    )

Behavior

Updates the version string in 6 files:

Step	File	Pattern	Replacement
1	Browser/version.py	__version__ = .*	__version__ = "19.13.0"
2	package.json	"version": ".*"	"version": "19.13.0"
3	package-lock.json	JSON manipulation (two fields)	"version": "19.13.0" at top level and in packages[""]
4	pyproject.toml (Browser)	version = ".*" (first occurrence)	version = "19.13.0"
5	browser_batteries/pyproject.toml	version = ".*" (first occurrence) AND dependencies = ["robotframework-browser==.*"]	Both updated
6	docker/Dockerfile.latest_release	robotframework-browser==.*	robotframework-browser==19.13.0

The helper _replace_version uses regex substitution:

def _replace_version(filepath, matcher, version, count=0):
    content = filepath.open().read()
    with open(filepath, "w") as out:
        out.write(matcher.sub(version, content, count))

The count parameter limits replacements (0 means replace all, 1 means replace first occurrence only).

Task: docs

Signature

@task
def docs(c, version=None):
    """Generate library keyword documentation."""

Parameters

Parameter	Type	Default	Description
version	str or None	None	When provided, saves docs to docs/versions/Browser-{version}.html

Behavior

1. Generates HTML documentation using Robot Framework's libdoc:

   output = ROOT_DIR / "docs" / "Browser.html"
   libdoc("Browser", str(output))
   

1. Post-processes the HTML using BeautifulSoup to inject Google Analytics tracking:
   • Adds an async script tag for googletagmanager.com/gtag/js
   • Adds an inline script for GA configuration with anonymized IP and hash change tracking

1. If version is provided, moves the file to docs/versions/Browser-{version}.html:

   if version is not None:
       target = ROOT_DIR / "docs" / "versions" / f"Browser-{version.replace('v', '')}.html"
       output.rename(target)
   

Task: release_notes

Signature

@task
def release_notes(c, version=None, username=None, password=None, write=False):
    """Generates release notes based on issues in the issue tracker."""

Parameters

Parameter	Type	Default	Description
version	str or None	None	Version to generate notes for; if None, uses current version from Browser/version.py
username	str or None	None	GitHub username (or GITHUB_USERNAME env var)
password	str or None	None	GitHub password/token (or GITHUB_PASSWORD env var)
write	bool	False	When True, writes to docs/releasenotes/Browser-{version}.md; otherwise prints to stdout

Source Code

@task
def release_notes(c, version=None, username=None, password=None, write=False):
    pattern = '__version__ = "(.*)"'
    if write and not RELEASE_NOTES_PATH.parent.is_dir():
        RELEASE_NOTES_PATH.parent.mkdir(parents=True)
    version = Version(version, VERSION_PATH, pattern)
    file = RELEASE_NOTES_PATH if write else sys.stdout
    generator = ReleaseNotesGenerator(
        REPOSITORY,
        RELEASE_NOTES_TITLE,
        RELEASE_NOTES_INTRO.replace("REPLACE_PW_VERSION", _get_pw_version()),
    )
    generator.generate(version, username, password, file)

Behavior

1. Reads the current version from Browser/version.py using the pattern __version__ = "(.*)"
2. Creates the release notes output directory if needed
3. Initializes a ReleaseNotesGenerator from the rellu library with:
   • Repository: MarketSquare/robotframework-browser
   • Title template: Browser library {version}
   • Introduction template: includes installation instructions and Playwright version
4. Generates notes by querying GitHub issues for the milestone
5. Writes to file or stdout depending on the write parameter

The introduction template includes dynamic content:

• The Playwright version is read from package.json dependencies
• Installation instructions for both Browser-only and BrowserBatteries setups

Configuration Constants

RELEASE_NOTES_PATH = Path("docs/releasenotes/Browser-{version}.md")
RELEASE_NOTES_TITLE = "Browser library {version}"
REPOSITORY = "MarketSquare/robotframework-browser"
VERSION_PATH = Path("Browser/version.py")

Related

• MarketSquare_Robotframework_browser_Release_Preparation -- Principle document for release preparation
• MarketSquare_Robotframework_browser_Github_Release_Workflow -- The publication workflow triggered after preparation
• MarketSquare_Robotframework_browser_Inv_Build -- Building is a prerequisite for docs generation