Improve git initialisation and initially included files. (#386)

MANIFEST.in

@@ -1,4 +1,3 @@
-include knowledge_repo/config_defaults.yml
 recursive-include knowledge_repo/templates *
 recursive-include knowledge_repo/app/templates *
 recursive-include knowledge_repo/app/static *

knowledge_repo/repositories/gitrepository.py

@@ -23,21 +23,41 @@
 class GitKnowledgeRepository(KnowledgeRepository):
     _registry_keys = ['', 'git']
 
+    TEMPLATES = {
+        'README.md': os.path.abspath(os.path.join(os.path.dirname(__file__), '../templates', 'repository_readme.md')),
+        '.knowledge_repo_config.yml': os.path.abspath(os.path.join(os.path.dirname(__file__), '../templates', 'repository_config.yml'))
+    }
+
     @classmethod
     def create(cls, uri):
         path = uri.replace('git://', '')
         if os.path.exists(path):
-            response = input('Repository already exists. Do you want to convert it to a knowledge data repository? Note that this will override any existing `README.md` and `.knowledge_repo_config.py` files, and replace any submodule at `.resources`. (y/n) ')
-            if response is not 'y':
-                logger.warning('Not updating existing repository. Aborting!')
-                return
+            try:
+                repo = git.Repo(path)
+                logger.warning("Repository already exists for uri '{}'. Checking if configuration is needed...".format(uri))
+            except git.InvalidGitRepositoryError:
+                if os.path.isdir(path):
+                    logger.warning("Upgrading existing directory at '{}' to a git knowledge repository...".format(path))
+                else:
+                    raise RuntimeError("File exists at nominated path: {}. Cannot proceed with repository initialization.".format(path))
+
         repo = git.Repo.init(path, mkdir=True)
-        shutil.copy(os.path.join(os.path.dirname(__file__), '../config_defaults.yml'),
-                    os.path.join(path, '.knowledge_repo_config.yml'))
-        shutil.copy(os.path.join(os.path.dirname(__file__), '../templates', 'repo_data_readme.md'),
-                    os.path.join(path, 'README.md'))
-        repo.index.add(['.knowledge_repo_config.yml', 'README.md'])
-        repo.index.commit("Initial creation of knowledge data repository structure.")
+
+        # Add README and configuration templates
+        added_files = 0
+
+        for filename, template in cls.TEMPLATES.items():
+            target = os.path.join(path, filename)
+            if not os.path.exists(target):
+                shutil.copy(template, target)
+                repo.index.add([filename])
+                added_files += 1
+            else:
+                logger.warning("Not overriding existing file '{}'.".format(filename))
+
+        if added_files > 0:
+            repo.index.commit("Initial creation of knowledge repository.")
+
         return GitKnowledgeRepository(path)
 
     def init(self, config='git:///.knowledge_repo_config.yml', auto_create=False):

knowledge_repo/templates/repository_config.yml

@@ -0,0 +1,49 @@
+# A default YAML configuration for the repository.
+# Please refer to config_defaults.py for documentation on what these options do
+
+# The accepted path patterns should be provided as a dictionary mapping regex
+# patterns to descriptions of that pattern.
+path_patterns:
+  '.*': "All paths are valid."
+
+# A dictionary of aliases which point to knowledge posts. This allows you to alias posts
+# which may be useful to forward old links to new locations, or to give certain posts
+# precedence. It also allows the post path to violate the normal naming rules of posts.
+# The only condition is that they cannot mask an existing post url, in which case the
+# alias is silently ignored.
+aliases: {}
+
+# Postprocessors to apply when importing KnowledgePost objects into the repository.
+# Note that KnowledgePost objects by default run 'extract_images' and 'format_checks'.
+# Order is important. Should be a list of lists, of form:
+# ['name of postprocessor', {'init_kwarg': 'value'}]
+postprocessors: []
+
+# Usernames of users to keep informed of changes to the knowledge data repo
+editors: []
+
+# A regex pattern to which valid usernames must adhere
+username_pattern: '.*'
+
+# A tuple/list of strings, the first being a regex with named groups, and the
+# second being a format string with the group names available.
+username_to_name_pattern: ['(?P<username>.*)', '{username}']
+
+# A tuple/list of strings, the first being a regex with named groups, and the
+# second being a format string with the group names available.
+username_to_email_pattern: ['(?P<username>.*)', '{username}@example.com']
+
+# The base url of the server hosting this repository.
+web_uri_base: ~
+
+# If administrators of this knowledge repository want to suggest a specific
+# knowledge_repo version requirement when interacting with the repository using
+# the `knowledge_repo` script, they may do so here. Users can always work around
+# this restriction by using the `--dev` flag to the `knowledge_repo` script. If
+# the value supplied is a string starting with '!', it is taken to refer to a
+# git tag or commit hash on the upstream Knowledge Repo repository, and the
+# `knowledge_repo` script will clone the required  Knowledge Repo version and
+# chain commands to it. Otherwise, it is interpreted as a pip-like version
+# description (e.g. '==x.y.z', '>0.1.2<=0.8.0', etc), and the currently running
+# version of the `knowledge_repo` library is checked at runtime.
+required_tooling_version: ~

knowledge_repo/templates/repository_readme.md

@@ -0,0 +1,59 @@
+# Knowledge Repository
+
+This is a git repository that stores documents called "Knowledge Posts" in a
+format compatible with the [Knowledge Repo](https://github.com/airbnb/knowledge-repo)
+project.
+
+If you are looking to contribute a post to this repository, please refer to the
+below quickstart guide or the [upstream documentation](http://knowledge-repo.readthedocs.io/en/latest/quickstart.html).
+
+## Quickstart
+
+1\. Install the knowledge-repo tooling
+```
+pip install  --upgrade "knowledge-repo[all]"
+```
+
+2\. Clone this repository to your local machine
+```
+git clone <git_url> <repo_path>
+```
+**Note:** If you regularly interact with this repository, you can avoid having to type `--repo <repo_path>` in all of the below commands by exporting a shell environment variable:
+
+```
+export KNOWLEDGE_REPO="<repo_path>"
+```
+
+3\. Create a post template
+
+For Jupyter notebooks:
+```
+knowledge_repo --repo <repo_path> create ipynb example_post.ipynb
+```
+
+For R Markdown:
+```
+knowledge_repo --repo <repo_path> create Rmd example_post.Rmd
+```
+
+4\. Edit the notebook file `example_post.ipynb` or `example_post.Rmd` as you normally would.
+
+5\. Add your post to the repo with in-repository path of `project/example`
+```
+knowledge_repo --repo <repo_path> add <post_path> -p project/example
+```
+
+6\. Preview the added post to ensure everything is rendering correctly
+```
+knowledge_repo --repo <repo_path> preview project/example
+```
+
+7\. Submit post as a new git branch in this repository
+```
+knowledge_repo --repo <repo_path> submit project/example
+```
+
+8\. Open a pull/merge request on your branch
+
+Once ready, merge your branch into master, and your post will shortly thereafter
+appear in attached *Knowledge Repo* servers.

scripts/knowledge_repo

@@ -13,6 +13,7 @@ import argparse
 import subprocess
 
 import git
+import gitdb
 import webbrowser
 from tabulate import tabulate
 
@@ -93,7 +94,7 @@ if args.repo is None:
 # initialised will be enforced.
 try:
     repo = knowledge_repo.KnowledgeRepository.for_uri(args.repo)
-except (ValueError, git.InvalidGitRepositoryError):  # TODO: Generalise error to cater for all KnowledgeRepository instances.
+except (ValueError, git.GitError, gitdb.exc.ODBError):  # TODO: Generalise error to cater for all KnowledgeRepository instances.
     repo = None
 
 
@@ -245,7 +246,7 @@ if args.action == 'init':
     assert not isinstance(args.repo, dict), "Only one repository can be initialised at a time."
     repo = knowledge_repo.KnowledgeRepository.create_for_uri(args.repo)
     if repo is not None:
-        print("Knowledge repository created for uri `{}`.".format(repo.uri))
+        print("Knowledge repository successfully initialized for uri `{}`.".format(repo.uri))
     else:
         print("Something weird happened while creating repository for uri `{}`. Please report!".format(repo.uri))
     sys.exit(0)