Add addtional documentation about contributing to the project, start …

…user and internal guides (#414) Co-authored-by: Amit Joshi <[email protected]>
AbanteAI · Jan 1, 2024 · ea55e95 · ea55e95
1 parent 808109e
commit ea55e95
Show file tree

Hide file tree

Showing 18 changed files with 76 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,4 @@ build
 .mentat_config.json
 .pytest_cache
 benchmark_repos
+docs/build
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# Welcome #
+
+We're so glad you're thinking about contributing to Mentat!  If you're unsure of anything feel free to ask us or submit an issue.  We appreciate any all contributions, and are excited to see what you add to Mentat!
+
+Before contributing, we encourage you to read our CONTRIBUTING policy (you are here), our [LICENSE](LICENSE), and our [README](README.md).
+
+## Issues ##
+
+If you want to report a bug or request a new feature, the most direct method is to [create an issue](https://github.com/AbanteAI/mentat/issues/new) in this repository.  We recommend that you first search through existing issues (both open and closed) to check if your particular issue has already been reported.  If it has then you might want to add a comment to the existing issue.  If it hasn't then feel free to create a new one.
+
+## Pull requests ##
+
+If you choose to [submit a pull request](https://github.com/AbanteAI/mentat/pulls), you will notice that our continuous integration (CI) system runs a fairly extensive set of linters and syntax checkers.  Your pull request may fail these checks, and that's OK.  If you want you can stop there and wait for us to make the necessary corrections to ensure your code passes the CI checks.
+
+If you want to make the changes yourself, or if you want to become a regular contributor, then you may find it helpful to set up [pre-commit](https://pre-commit.com/) on your local machine.  pre-commit will run the CI checks  locally before you even write your commit message, which can speed up the development cycle considerably.
+
+## Getting Started
+
+### Contribution Process
+
+Mentat follows the usual open source contribution process on Github. In order to contribute, you must fork the repository, create a branch based on the main branch, make your changes there and then create a pull request. Github has excellent documentation (and contributed documentation and videos) on how to do this. See [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project), [first contributions](https://github.com/firstcontributions/first-contributions) for more details.
+
+The project, like most projects, does have some customizations specific to Mentat such as code formatting, quality checks which are enforced on each pull request using Github actions. Pull Requests (PRs - described later) are not accepted unless all the checks are passed.
+
+### Setup the Environment
+
+Mentat requires Python (version 3.10 or later) for development. The source code comes with two sets of requirements. The first in requirements.txt are needed to run Mentat. The second additional requirements in dev-requirements.txt are needed to do development work. As a contributor you will need to install both sets of requirements. In addition, you may need some tools outside of the python environment. 
+
+#### Python Virtual Environment setup
+
+We recommend using a python virtual environment dedicated to Mentat development to avoid any conflicts with other projects. One tutorial on setting up python virtual environments can be found here: [Python Virtual Environments](https://www.arch.jhu.edu/python-virtual-environments/). 
+
+##### Conda (anaconda) Specific Notes
+
+Since not all the requirements are available in the conda repositories, it will be necessary to use pip to install the requirements. In order to avoid conflicts between installation using conda and pip you should add the following to your `.condarc` file (the location of the file varies based on the OS - but typically is in the users home directory):
+
+```
+pip_interop_enabled: true
+```
+
+## Code review and Merge approval ##
+
+In order to maintain standardization of practices, ensure security standards are being met, and to incorporate third party code as seamlessly as possible, all submitted code will go through a code review and merge approval process.
+
+Code contributors are able to coordinate with the Mentat team at any point during the contribution process. We recommend initiating the discussions as early as possible, to decrease the likelihood of issues around merging or using the contributed code occurring late in the process. 
+
+## Attribution ##
+
+This file is based on the CONTRIBUTING.md document from the public domain [development-guide](https://github.com/cisagov/development-guide) project.
+
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -8,4 +8,5 @@ pytest-xdist==3.3.1
 ruff==0.0.292
 sphinx==7.2.6
 sphinx-rtd-theme==2.0.0
+sphinx-argparse==0.4.0 
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,6 +22,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    "sphinxarg.ext",
 ]
 
 templates_path = ["_templates"]

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,6 +10,8 @@ Welcome to Mentat's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   user/guides
+   internal/modules
 
 
 Indices and tables

diff --git a/docs/source/mentat.command.commands.rst → ...urce/internal/mentat.command.commands.rst b/docs/source/mentat.command.commands.rst → ...urce/internal/mentat.command.commands.rst
diff --git a/docs/source/mentat.command.rst → docs/source/internal/mentat.command.rst b/docs/source/mentat.command.rst → docs/source/internal/mentat.command.rst
diff --git a/docs/source/mentat.feature_filters.rst → ...ource/internal/mentat.feature_filters.rst b/docs/source/mentat.feature_filters.rst → ...ource/internal/mentat.feature_filters.rst
diff --git a/docs/source/mentat.parsers.rst → docs/source/internal/mentat.parsers.rst b/docs/source/mentat.parsers.rst → docs/source/internal/mentat.parsers.rst
diff --git a/docs/source/mentat.prompts.rst → docs/source/internal/mentat.prompts.rst b/docs/source/mentat.prompts.rst → docs/source/internal/mentat.prompts.rst
diff --git a/docs/source/mentat.python_client.rst → .../source/internal/mentat.python_client.rst b/docs/source/mentat.python_client.rst → .../source/internal/mentat.python_client.rst
diff --git a/docs/source/mentat.rst → docs/source/internal/mentat.rst b/docs/source/mentat.rst → docs/source/internal/mentat.rst
diff --git a/docs/source/mentat.terminal.rst → docs/source/internal/mentat.terminal.rst b/docs/source/mentat.terminal.rst → docs/source/internal/mentat.terminal.rst
diff --git a/docs/source/mentat.vision.rst → docs/source/internal/mentat.vision.rst b/docs/source/mentat.vision.rst → docs/source/internal/mentat.vision.rst
diff --git a/docs/source/modules.rst → docs/source/internal/modules.rst b/docs/source/modules.rst → docs/source/internal/modules.rst
diff --git a/docs/source/user/guides.rst b/docs/source/user/guides.rst
@@ -0,0 +1,7 @@
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 4
+
+   usage
diff --git a/docs/source/user/usage.rst b/docs/source/user/usage.rst
@@ -0,0 +1,7 @@
+Mentat Usage
+============
+
+.. argparse:: 
+   :prog: mentat
+   :module: mentat.terminal.client
+   :func: get_parser
diff --git a/mentat/terminal/client.py b/mentat/terminal/client.py
@@ -194,7 +194,7 @@ def run(self):
         asyncio.run(self._run())
 
 
-def run_cli():
+def get_parser():
     parser = argparse.ArgumentParser(
         description="Run conversation with command line args"
     )
@@ -240,8 +240,13 @@ def run_cli():
     parser.add_argument(
         "--cwd", default=Path.cwd(), help="The current working directory"
     )
-
     Config.add_fields_to_argparse(parser)
+    return parser
+
+
+def run_cli():
+    parser = get_parser()
+
     args = parser.parse_args()
 
     cwd = Path(args.cwd).expanduser().resolve()