Update documentation (#233)

- Change "khiops-python" to "Khiops Python library"
- Eliminate old conda-build documentation
- Removed obsolete conda doc
- Other minor changes

Author: folmos-at-orange

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 **Notes:**
 - Versioning: The versioning scheme depends on the Khiops version supported (first 3 digits) and
-  a `khiops-python` correlative (4th digit).
+  a Khiops Python Library correlative (4th digit).
   - Example: 10.2.1.4 is the 5th version that supports khiops 10.2.1.
 - Internals: Changes in *Internals* sections are unlikely to be of interest for data scientists.
 
@@ -71,10 +71,10 @@
 
 ## 10.2.0.0 - 2024-02-15
 Note: This release marks the open sourcing of Khiops:
-- The `khiops-python` replaces the old `pykhiops` package. We recommend to uninstall `pykhiops`
-  before installing `khiops-python`. More information at the [Khiops website][khiops].
-- `khiops-python` uses a new four digit versioning convention.
-- The `khiops` conda package is available for many environments. See the [Khiops website][khiops]
+- The `khiops` package replaces the old `pykhiops` package. We recommend to uninstall
+  `pykhiops` before installing `khiops`. More information at the [Khiops site][khiops].
+- The `khiops` package uses a new four digit versioning convention.
+- The `khiops` conda package is available for many environments. See the [Khiops site][khiops]
   for more information.
 
 ### Added

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-# khiops-python Coding Guidelines
+# Khiops Python Library Coding Guidelines
 
 ## Quick Start
 ```bash
-# Make sure you are a member of the pyKhiops GitHub project and that you have set up the SSH keys
+# Make sure you are a member of the khiops-python GitHub project and that you have set up the SSH keys
 # for Git
 
 # Clone the repo
@@ -28,11 +28,11 @@ python -m unittest tests.test_sklearn.KhiopsSklearnParameterPassingTests
 ## Coding Style
 
 ### Language
-`khiops-python` is coded in English (comments included).
+We code in English (comments included).
 
 ### Style Enforcement: Tools & Git Hooks
-The coding style of pyKhiops is almost PEP8 compliant. To enforce these guidelines we use three
-tools:
+The coding style of the Khiops Python library is almost PEP8 compliant. To enforce these guidelines
+we use three tools:
 - [Black](https://github.com/psf/black)
 - [isort](https://pycqa.github.io/isort/)
 - [Pylint](https://www.pylint.org/)
@@ -151,7 +151,7 @@ rebase before the last merge commit.
 A usual application of history rewriting is to eliminate commits named "Fix previous commit". In
 this case use `rebase` to rewrite the history as follows:
 ```bash
-git rebase -i <REF-TO-FIX> # Usually REF-TO-FIX is either "develop", "HEAD~2" or a specific hash
+git rebase -i <ROOT-REF> # Usually ROOT-REF is either "dev", "HEAD~2" or a specific hash
 ```
 to interactively move and squash fix commits with the `fixup` or `squash` operator. Usually this
 operation will make your feature branch diverge from `origin` (GitHub repo), so a `git push --force`
@@ -241,10 +241,16 @@ For development dependencies (eg. `black`, `isort`, `sphinx`, `wrapt`, `furo`) w
 carefree while still trying to not add too many dependencies.
 
 ## Versioning
-We follow a non-standard `MAJOR.MINOR.PATCH.INCREMENT[PRE_RELEASE]` versioning convention. The
+We follow a non-standard `MAJOR.MINOR.PATCH.INCREMENT[-PRE_RELEASE]` versioning convention. The
 first three numbers `MAJOR.MINOR.PATCH` are the latest Khiops version that is compatible with the
-package. The number `INCREMENT` indicates the evolution of `khiops-python` followed by an optional
-`[PRE_RELEASE]` version for alpha, beta and release candidate releases (eg. `b2`).
+package. The number `INCREMENT` indicates the evolution of the Khiops Python library followed by an
+optional `[-PRE_RELEASE]` version for alpha, beta and release candidate releases (eg. `b.2`).
+
+**Important Note:** For the versions of packages we remove the dash `-` before the `PRE_RELEASE`
+atom to be compatible with the [Python version specifiers][python-version-spec], which is required
+by `pip` and `conda`.
+
+[python-version-spec]: https://packaging.python.org/en/latest/specifications/version-specifiers/#version-specifiers
 
 ## Releases
 
@@ -292,6 +298,3 @@ Checklist:
 To make a public release, you must execute the `Conda Package` CI workflow manually on a tag and
 specify the `khiops` anaconda channel for upload. These uploads do not overwrite any packages in
 this channel, so you must correct any mistake manually.
-
-### Git Manipulations upon a Major Release
-The following is the check list to be done upon a major release:

README.md

@@ -1,6 +1,6 @@
-# Khiops Python
+# Khiops Python Library
 
-**Khiops Python** is a Python library for the [Khiops AutoML suite][khiops].
+This is the repository of the **Khiops Python Library** for the [Khiops AutoML suite][khiops].
 
 ## Description
 Khiops is a robust AutoML suite for constructing supervised models (classifiers, regressors and
@@ -31,7 +31,8 @@ Other install method are documented at the [Khiops website][khiops-install].
 [sklearn]: https://scikit-learn.org/stable
 
 ## Documentation
-The main documentation of the Khiops Python library is available [here][khiops-python-doc].
+The API Docs for the Khiops Python library are available [here][khiops-api-docs]. Other
+documentation (algorithms, installation, etc) may be found in the [Khiops site][khiops].
 
 The library itself is documented with docstrings: for example to obtain help on the
 `train_predictor` function you can use:
@@ -54,7 +55,7 @@ Team: khiops.team@orange.com .
 
 [khiops]: https://khiops.org
 [khiops-install]: https://khiops.org/setup
-[khiops-python-doc]: https://khiopsml.github.io/khiops-python
+[khiops-api-docs]: https://khiopsml.github.io/khiops-python
 [python]: https://www.python.org
 [pandas]: https://pandas.pydata.org
 [sklearn]: https://scikit-learn.org/stable

doc/tools/index.rst

@@ -1,6 +1,6 @@
 Tools
 =====
-These are auxiliary tools to the ``khiops-python`` installation.
+These are auxiliary tools for the Khiops Python library.
 
 .. currentmodule:: khiops
 .. autosummary::

khiops/core/internals/runner.py

@@ -360,7 +360,7 @@ def __init__(self):
         self._khiops_version = None
         self._samples_dir = None
 
-        # Whether to write the khiops-python version of the scenarios
+        # Whether to write the Khiops Python library version of the scenarios
         # For development uses only
         self._write_version = True
 
@@ -393,7 +393,7 @@ def root_temp_dir(self):
         r"""str: The runner's temporary directory
 
         The temporary scenarios/templates and dictionary files created by
-        khiops-python are stored here.
+        the Khiops Python library are stored here.
 
         Default value:
             - Windows: ``%TEMP%\khiops\python``
@@ -619,7 +619,7 @@ def _build_status_message(self):
         if caught_warnings is not None:
             warning_list += caught_warnings
 
-        status_msg = "khiops-python settings\n"
+        status_msg = "Khiops Python library settings\n"
         status_msg += f"version             : {khiops.__version__}\n"
         status_msg += f"runner class        : {self.__class__.__name__}\n"
         status_msg += f"max cores           : {self.max_cores}"
@@ -641,14 +641,14 @@ def print_status(self):
         try:
             status_msg, warning_list = self._build_status_message()
         except (KhiopsEnvironmentError, KhiopsRuntimeError) as error:
-            print(f"khiops-python status KO: {error}")
+            print(f"Khiops Python library status KO: {error}")
             return 1
 
         # Print status details
         print(status_msg, end="")
 
         # Print status
-        print("khiops-python status OK", end="")
+        print("Khiops Python library status OK", end="")
         if warning_list:
             print(", with warnings:")
             for warning in warning_list:
@@ -1415,21 +1415,21 @@ def _initialize_khiops_version(self):
         else:
             khiops_version_str, _, _, _ = _get_tool_info_khiops9(self, "khiops")
             warnings.warn(
-                "Khiops version is earlier than 10.0; khiops-python will "
+                "Khiops version is earlier than 10.0; the Khiops Python library will "
                 f"run in legacy mode. Khiops path: {self._tool_path('khiops')}",
                 stacklevel=3,
             )
         self._khiops_version = KhiopsVersion(khiops_version_str)
 
-        # Warn if the khiops version is too far from the khiops-python version
+        # Warn if the khiops version is too far from the Khiops Python library version
         compatible_khiops_version = khiops.get_compatible_khiops_version()
         if self._khiops_version.major > compatible_khiops_version.major:
             warnings.warn(
                 f"Khiops version '{self._khiops_version}' is ahead of "
-                f"the khiops-python version '{khiops.__version__}'. "
+                f"the Khiops Python library version '{khiops.__version__}'. "
                 "There may be compatibility errors and "
-                "we recommend you to update to the latest khiops-python version."
-                "Go to https://khiops.org for more information.",
+                "we recommend you to update to the latest Khiops Python "
+                "library version. See https://khiops.org for more information.",
                 stacklevel=3,
             )
 

khiops/samples/samples.py

@@ -1693,7 +1693,7 @@ def execute_samples(args):
 
     # Print the execution title
     if execution_samples:
-        print(f"khiops-python {khiops.__version__} running on Khiops ", end="")
+        print(f"Khiops Python library {khiops.__version__} running on Khiops ", end="")
         print(f"{kh.get_khiops_version()}\n")
         print(f"Sample datasets location: {kh.get_samples_dir()}")
         print(f"{len(execution_samples)} sample(s) to execute\n")

khiops/samples/samples_sklearn.py

@@ -975,7 +975,7 @@ def execute_samples(args):
 
     # Print the execution title
     if execution_samples:
-        print(f"khiops-python {khiops.__version__} running on Khiops ", end="")
+        print(f"Khiops Python library {khiops.__version__} running on Khiops ", end="")
         print(f"{kh.get_khiops_version()}\n")
         print(f"Sample datasets location: {kh.get_samples_dir()}")
         print(f"{len(execution_samples)} sample(s) to execute\n")