Merge pull request #22 from whisk-ml/project-name

Deriving the project name from `src/<project name>`

CHANGELOG.rst

@@ -6,3 +6,8 @@ Changelog
 ------------------
 
 * First release on PyPI.
+
+0.1.28 (2020-05-17)
+------------------
+
+* Deriving the project name from `src/<project name>` vs. the top-level directory name.

docs/guides.md

@@ -0,0 +1,10 @@
+# Guides
+
+The guides below provide a step-by-step walkthrough of common tasks inside whisk projects.
+
+```eval_rst
+.. toctree::
+   :maxdepth: 2
+
+   rename_project
+```

docs/index.md

@@ -49,6 +49,7 @@ The [whisk-ml](https://github.com/whisk-ml) GitHub org contains example whisk pr
    dvc
    heroku
    packaging
+   guides
    modules
    changelog
    contributing

docs/rename_project.md

@@ -0,0 +1,44 @@
+# Renaming a project
+
+Follow the following steps if you wish to change the name of a whisk project.
+
+## 1. Update setup.py
+
+In the project's `setup.py` file, update the `setup` function's `name` argument and the cli command:
+
+```diff
+-    name='<old project name>',
++    name='<new project name>',
+      entry_points={
+        'console_scripts': [
+-            '<old project name>=<old project name>.cli.main:cli',
++            '<new project name>=<new project name>.cli.main:cli',
+        ],
+    },
+```
+
+## 2. Update the src/<project name> directory
+
+Rename the `src/<project name>` directory:
+
+    mv src/<old project name> src/<new project name>
+
+## 3. Find and replace the project name in project files
+
+In your project files, find and replace `<old project name>.` with `<new project name>.`
+
+## 4. Re-install the package
+
+Type the following to re-install the package in editable mode:
+
+    pip install -e .
+
+## 5. Run tests
+
+Run both `pytest` and `tox` to ensure all tests pass with the new project name.
+
+## Extra considerations
+
+### DVC
+
+If your project is using [DVC](dvc.html), you may need to run [`dvc move`](https://dvc.org/doc/command-reference/move) to update the paths of files tracked with DVC.

whisk/project.py

@@ -26,8 +26,8 @@ def __init__(self, dir=os.getcwd(), module_dir=None):
         """The top-level project directory (str)"""
         self.path = Path(self.dir)
         """The top-level project directory as a pathlib.Path"""
-        self.name = self.path.stem
-        """Name of the project derived from the top-level directory (str)"""
+        self.name = self.name_from_src_dir(self.path / "src")
+        """Name of the project derived from the src/<project_name> directory (str)"""
         self.module_dir = module_dir
         """
         Location of the project's module directory as a pathlib.Path.
@@ -54,6 +54,22 @@ def __init__(self, dir=os.getcwd(), module_dir=None):
             Returns `None` if not within a whisk project.
             """
 
+    def name_from_src_dir(self, src_dir):
+        """
+        Derives the project name from the first child directory in the ``src/``
+        directory that contains an ``__init__.py`` file.
+
+        Parameters
+        ----------
+        src_dir : pathlib.Path
+            Path object referencing the project ``src/`` directory.
+        """
+
+        src_children = sorted(src_dir.glob("*/__init__.py"))
+        if len(src_children) == 0:
+            return None
+        return src_children[0].parent.stem
+
     def validate_in_project(self):
         """
         Raises an `OSError` if this is not a whisk project.

whisk/whisk.py

@@ -17,14 +17,23 @@ def root_module_dir():
 def cookiecutter_template_dir():
     return str(root_module_dir() / 'template/')
 
+def project_name_to_slug(project_name):
+    """
+    Converts a raw project name to a slug:
+
+    * Makes all letters lowercase
+    * Replaces spaces with underscores
+    """
+    return project_name.lower().replace(' ', '_')
+
 def create(project_name, output_dir=".", setup=None, force=False):
     """
     Creates a whisk project.
 
     Parameters
     ----------
     project_name : str
-        Name of the directory to create for the project.
+        Name of the directory to create for the project. This is converted to a slug via :func:`project_name_to_slug`.
 
     output_dir : str, optional
         Path to create the directory. Default is the current working directory.
@@ -38,10 +47,13 @@ def create(project_name, output_dir=".", setup=None, force=False):
     # Locks to a specific version as earlier and later versions of whisk could expect a different
     # template structure.
     whisk_version = "whisk=={}".format(whisk.__version__)
+
+    project_name_slug = project_name_to_slug(project_name)
+
     # `whisk_dependency` is more flexible (for example, specifying a local install)
     # than `whisk_install_requires` and is used in testing to require the local version of whisk.
     extra_content = {
-        "project_name": project_name,
+        "project_name": project_name_slug,
         # Added to the project's requirements.txt
         "whisk_dependency": whisk_version,
         # Added to the project's setup.py file