generated documentation for click cli

[dholth]

Description

A nice generated documentation.

Is the HTML included in the CI artifacts, if we want to look at it before merge?

I noticed the sphinx_click documentation says the threads flag defaults to 10 (the number of cores on the machine I built the documentation on). Would be different for GHA-built docs. Is there a way to avoid that? (Maybe set show-default to False on the click cli, and write "defaults to the # of processors in your system" in that text?)

Checklist - did you ...

• Add a file to the news directory (using the template) for the next release's release notes?
• Add / update necessary tests?
• Add / update outdated documentation?

[barabo]

There are still 2 failing unit tests with the latest update, which I suspect may need some additional attention.

Click for details...

(base) @barabo ➜ /workspaces/conda-index (foss-friday) $ pytest
================================================================================================== test session starts ===================================================================================================
platform linux -- Python 3.10.9, pytest-7.2.1, pluggy-1.0.0
rootdir: /workspaces/conda-index, configfile: pyproject.toml, testpaths: tests
plugins: anyio-3.6.2, cov-4.0.0, mock-3.10.0
collected 33 items                                                                                                                                                                                                       

tests/test_coverage.py .........                                                                                                                                                                                   [ 27%]
tests/test_groupby_strategies.py .                                                                                                                                                                                 [ 30%]
tests/test_index.py ...........FF...                                                                                                                                                                               [ 78%]
tests/test_rss.py ......                                                                                                                                                                                           [ 96%]
tests/test_utils.py .                                                                                                                                                                                              [100%]

======================================================================================================== FAILURES ========================================================================================================
____________________________________________________________________________________________ test_current_index_reduces_space ____________________________________________________________________________________________

index_data = PosixPath('/tmp/pytest-of-codespace/pytest-3/test_current_index_reduces_spa0/index_data')

    @pytest.mark.skipif(
        not hasattr(context, "use_only_tar_bz2") or getattr(context, "use_only_tar_bz2"),
        reason="conda is set to auto-disable .conda for old conda-build.",
    )
    def test_current_index_reduces_space(index_data):
        repodata = Path(index_data, "time_cut", "repodata.json")
        with open(repodata) as f:
            repodata = json.load(f)
        assert len(repodata["packages"]) == 7
        assert len(repodata["packages.conda"]) == 3
        trimmed_repodata = conda_index.index._build_current_repodata(
            "linux-64", repodata, None
        )
    
        tar_bz2_keys = {
            "two-because-satisfiability-1.2.11-h7b6447c_3.tar.bz2",
            "two-because-satisfiability-1.2.10-h7b6447c_3.tar.bz2",
            "depends-on-older-1.2.10-h7b6447c_3.tar.bz2",
            "ancient-package-1.2.10-h7b6447c_3.tar.bz2",
            "one-gets-filtered-1.3.10-h7b6447c_3.tar.bz2",
        }
        # conda 4.7 removes .tar.bz2 files in favor of .conda files
        if conda_47:
            tar_bz2_keys.remove("one-gets-filtered-1.3.10-h7b6447c_3.tar.bz2")
    
        # .conda files will replace .tar.bz2 files.  Older packages that are necessary for satisfiability will remain
        assert set(trimmed_repodata["packages"].keys()) == tar_bz2_keys
        if conda_47:
>           assert set(trimmed_repodata["packages.conda"].keys()) == {
                "one-gets-filtered-1.3.10-h7b6447c_3.conda"
            }
E           AssertionError: assert {'one-gets-fi...447c_3.conda'} == {'one-gets-fi...447c_3.conda'}
E             Extra items in the left set:
E             'one-gets-filtered-1.2.10-h7b6447c_3.conda'
E             'one-gets-filtered-1.2.11-h7b6447c_3.conda'
E             Use -v to get more diff

tests/test_index.py:975: AssertionError
__________________________________________________________________________________ test_current_index_version_keys_keep_older_packages ___________________________________________________________________________________

index_data = PosixPath('/tmp/pytest-of-codespace/pytest-3/test_current_index_version_key0/index_data')

    def test_current_index_version_keys_keep_older_packages(index_data):
        pkg_dir = Path(index_data, "packages")
    
        # pass no version file
        conda_index.api.update_index(pkg_dir)
        with open(os.path.join(pkg_dir, "osx-64", "current_repodata.json")) as f:
            repodata = json.load(f)
        # only the newest version is kept
>       assert len(repodata["packages"]) == 1
E       AssertionError: assert 2 == 1
E        +  where 2 = len({'dummy-package-1.0-0.tar.bz2': {'build': '0', 'build_number': 0, 'depends': ['python 2.7.*'], 'md5': 'fe3ca1adcd2b779...r.bz2': {'build': '0', 'build_number': 0, 'depends': ['python 2.7.*'], 'md5': '621277e18c2627643b156a0f3fad3082', ...}})

tests/test_index.py:1002: AssertionError
-------------------------------------------------------------------------------------------------- Captured stderr call --------------------------------------------------------------------------------------------------
2023-03-12T01:32:49 Subdir: noarch Gathering repodata
2023-03-12T01:32:49 noarch Writing pre-patch repodata
2023-03-12T01:32:49 noarch Applying patch instructions
2023-03-12T01:32:49 noarch Writing patched repodata
2023-03-12T01:32:49 noarch Building current_repodata subset
2023-03-12T01:32:49 noarch Writing current_repodata subset
2023-03-12T01:32:49 noarch Writing index HTML
2023-03-12T01:32:49 Subdir: osx-64 Gathering repodata
2023-03-12T01:32:49 osx-64 Writing pre-patch repodata
2023-03-12T01:32:49 osx-64 Applying patch instructions
2023-03-12T01:32:49 osx-64 Writing patched repodata
2023-03-12T01:32:49 osx-64 Building current_repodata subset
2023-03-12T01:32:49 osx-64 Writing current_repodata subset
2023-03-12T01:32:49 osx-64 Writing index HTML

---------- coverage: platform linux, python 3.10.9-final-0 -----------
Name                                 Stmts   Miss  Cover
--------------------------------------------------------
conda_index/__init__.py                  1      0   100%
conda_index/__main__.py                  2      2     0%
conda_index/api.py                      12      2    83%
conda_index/cli/__init__.py             33     33     0%
conda_index/index/__init__.py          542     53    90%
conda_index/index/common.py              8      0   100%
conda_index/index/convert_cache.py     143     71    50%
conda_index/index/logutil.py             3      0   100%
conda_index/index/rss.py                39      1    97%
conda_index/index/sqlitecache.py       240     34    86%
conda_index/utils.py                    29      0   100%
conda_index/utils_build.py             236    170    28%
conda_index/yaml.py                      9      0   100%
--------------------------------------------------------
TOTAL                                 1297    366    72%

================================================================================================ short test summary info =================================================================================================
FAILED tests/test_index.py::test_current_index_reduces_space - AssertionError: assert {'one-gets-fi...447c_3.conda'} == {'one-gets-fi...447c_3.conda'}
FAILED tests/test_index.py::test_current_index_version_keys_keep_older_packages - AssertionError: assert 2 == 1
============================================================================================= 2 failed, 31 passed in 59.22s ==============================================================================================

[kathatherine]

Found one comma typo. Is there an easy way to see these docs built? It's not completely clear to me how they look from the source code.

[kathatherine]

This page is showing up as blank for me in the build artifacts for this PR.

[kathatherine]

Looks good to me overall. Only thing is, in the CLI help that's now showing up for me in the doc artifact, the --channeldata, --rss, --bz2, and zst flags having question marks in their help text looks like a mistake from my perspective. Or like you're not sure. Those should probably just be periods or maybe "Generates or doesn't generate channeldata.json." "Writes or doesn't write rss.xml." Etc.

[dholth]

We can source the activate script instead, since conda init; conda activate does not work here.