Merge pull request #255 from trthhrtz/generate-contributing

Add generate contributing command

.gitignore

@@ -21,6 +21,8 @@ pip-wheel-metadata/
 
 /README.rst
 .idea
-.venv/
+.venv
+
+venv/
 
 \.python-version

dephell/actions/__init__.py

@@ -3,6 +3,7 @@
 
 # app
 from ._autocomplete import make_bash_autocomplete, make_zsh_autocomplete
+from ._contributing import make_contributing
 from ._converting import attach_deps
 from ._docker import get_docker_container
 from ._dotenv import read_dotenv
@@ -36,6 +37,7 @@
     'git_commit',
     'git_tag',
     'make_bash_autocomplete',
+    'make_contributing',
     'make_editorconfig',
     'make_json',
     'make_travis',

dephell/actions/_contributing.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# external
+from jinja2 import Environment, PackageLoader
+
+
+env = Environment(loader=PackageLoader('dephell', 'templates'))
+KNOWN_SECTIONS = (
+    ('test', 'tests'),
+    ('tests', 'tests'),
+    ('testing', 'tests'),
+    ('unittest', 'tests'),
+    ('pytest', 'tests'),
+
+    ('linter', 'lint'),
+    ('linters', 'lint'),
+    ('flake', 'lint'),
+    ('pylint', 'lint'),
+    ('flake8', 'lint'),
+
+    ('types', 'typing'),
+    ('typing', 'typing'),
+    ('mypy', 'typing'),
+
+    ('isort', 'isort'),
+    ('sort', 'isort'),
+)
+
+
+def make_contributing(config: Dict[str, Dict[str, Any]], project_path: Path) -> Optional[str]:
+    template = env.get_template('contributing.md.j2')
+    envs = dict()
+    for name, category in KNOWN_SECTIONS:
+        if name not in config:
+            continue
+        envs[category] = name
+    content = template.render(project_name=project_path.name, envs=envs)
+    while '\n\n\n' in content:
+        content = content.replace('\n\n\n', '\n\n')
+    return content

dephell/actions/_travis.py

@@ -31,7 +31,7 @@
 PYTEST = """
     - python: "3.5"
       env: ENV={env}
-    - python: "3.6"
+    - python: "3.6.7"
       env: ENV={env}
     - python: "3.7"
       env: ENV={env}

dephell/commands/discover.py

@@ -27,6 +27,7 @@
 
     'generate authors',
     'generate config',
+    'generate contributing',
     'generate editorconfig',
     'generate license',
     'generate travis',

dephell/commands/generate_contributing.py

@@ -0,0 +1,43 @@
+# built-in
+from argparse import ArgumentParser
+from pathlib import Path
+
+# external
+import tomlkit
+
+# app
+from ..actions import make_contributing
+from ..config import builders
+from .base import BaseCommand
+
+
+class GenerateContributingCommand(BaseCommand):
+    """Create CONTRIBUTING.md for DepHell-based project.
+    """
+    file_name = 'CONTRIBUTING.md'
+
+    @classmethod
+    def get_parser(cls) -> ArgumentParser:
+        parser = cls._get_default_parser()
+        builders.build_config(parser)
+        builders.build_output(parser)
+        builders.build_other(parser)
+        return parser
+
+    def __call__(self) -> bool:
+        if self.args.config:
+            path = Path(self.args.config)
+        else:
+            path = Path(self.config['project']) / 'pyproject.toml'
+            if not path.exists():
+                self.logger.error('cannot generate file without config')
+                return False
+
+        with path.open('r', encoding='utf8') as stream:
+            config = tomlkit.parse(stream.read())
+        config = dict(config['tool']['dephell'])
+        project_path = Path(self.config['project'])
+        text = make_contributing(config=config, project_path=project_path)
+        (project_path / self.file_name).write_text(text)
+        self.logger.info('generated', extra=dict(file=self.file_name))
+        return True

dephell/templates/contributing.md.j2

@@ -0,0 +1,73 @@
+# Contributing to {{ project_name }}
+
+Thank you for deciding to contribute to {{ project_name }}!  This guide is to assist you with contributing code. If you have a question that isn't answered here, please [open an issue][open issue].
+
+## The basics
+
+So you want to contribute some code?  Great! Here are the basic steps:
+
+1. Find an [issue][issues] that you want to work on. Good places to start are [good first issues] or [help wanted]. You could also [open an issue][open issue] if there is something specific you want to contribute. Wait for a response before you start coding though, as the thing you want might already exist somewhere!
+1. Fork {{ project_name }}.
+1. Clone your fork.
+1. Create a branch to work against.
+1. Run tests to make sure they work for your system.
+{% if 'tests' in envs %}
+1. Write some tests.
+{% endif %}
+1. Write some code.
+1. Run tests to make sure it works.
+{% if 'lint' in envs %}
+1. Run linters.
+{% endif %}
+1. Document changes.
+1. Push your branch (to your fork).
+1. Create a pull request to {{ project_name }}/master.
+1. Wait for checks to run and fix anything that was wrong.
+
+{% if 'tests' in envs %}
+## Testing
+
+Any new code that you contribute will be ideally covered under an automated test. To run existing tests:
+
+dephell venv create --env {{ envs['tests'] }}
+dephell deps install --env {{ envs['tests'] }}
+dephell venv run --env {{ envs['tests'] }}
+
+To write new tests using [pytest], place them in the `tests` directory.  This directory should roughly follow the same file structure as the source directory.
+{% endif %}
+
+{% if 'lint' in envs %}
+## Style
+
+Follow [PEP8]. Run linter to see how you're doing:
+
+```bash
+dephell venv create --env {{ envs['lint'] }}
+dephell deps install --env {{ envs['lint'] }}
+dephell venv run --env {{ envs['lint'] }}
+```
+
+{% if 'isort' in envs %}
+Sort imports before pushing:
+
+```bash
+dephell venv create --env {{ envs['isort'] }}
+dephell deps install --env {{ envs['isort'] }}
+dephell venv run --env {{ envs['isort'] }}
+```
+{% endif %}
+
+Main things you contribute are ideas and implementation. So, if you struggled with flake8 checks, don't worry, just ask help of maintainers in comments to your Pull Request. If your code passed CI, merging of Pull Request can't be rejected or delayed because of style. No [bikeshedding](https://en.wikipedia.org/wiki/Law_of_triviality) and meaningless discussions.
+{% endif %}
+
+## Using an IDE
+
+If you want to use an IDE to edit / test {{ project_name }} code, you'll have to point that IDE to the virtual environment. You can either get this path using `dephell inspect venv` or create the venv in a directory your IDE will find (e.g. `dephell venv create --venv .venv`).
+
+[issues]: {{ url }}/issues?utf8=✓&q=is%3Aissue+is%3Aopen+
+[open issue]: {{ url }}/issues/new
+[help wanted]: {{ url }}/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
+[good first issues]: {{ url }}/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+
+[pytest]: https://docs.pytest.org/en/latest/
+[PEP8]: https://www.python.org/dev/peps/pep-0008/

docs/cmd-generate-contributing.md

@@ -0,0 +1,8 @@
+# dephell generate contributing
+
+Adds `CONTRIBUTING.md` for your project. It reads environments from the dephell config and looks for some known environments, like `pytest`, `typing`, `flake8`. For every such environment a section with instructions will be created in the output file.
+
+## See also
+
+1. [dephell generate license](cmd-generate-license) to make LICENSE file for project.
+1. [dephell generate travis](cmd-generate-travis) to generate config for TravisCI.

docs/index-generate.md

@@ -1,13 +1,14 @@
 # **generate**: files generation
 
-Commands to generate useful files based on project metadata: [AUTHORS](cmd-generate-authors), [pyproject.toml](cmd-generate-config), [.editorconfig](cmd-generate-editorconfig), [LICENSE](cmd-generate-license), [.travis.yml](cmd-generate-travis).
+Commands to generate useful files based on project metadata: [AUTHORS](cmd-generate-authors), [pyproject.toml](cmd-generate-config), [.editorconfig](cmd-generate-editorconfig), [LICENSE](cmd-generate-license), [.travis.yml](cmd-generate-travis), [CONTRIBUTING.md](cmd-generate-contributing).
 
 ```eval_rst
 .. toctree::
     :maxdepth: 1
 
     cmd-generate-authors
     cmd-generate-config
+    cmd-generate-contributing
     cmd-generate-editorconfig
     cmd-generate-license
     cmd-generate-travis

tests/test_commands/test_generate_contributing.py

@@ -0,0 +1,32 @@
+# built-in
+from textwrap import dedent
+
+# project
+from dephell.commands import GenerateContributingCommand
+from dephell.config import Config
+
+
+def test_make_contributing_pytest(temp_path):
+    (temp_path / 'pyproject.toml').write_text(dedent(
+        """
+        [tool.dephell.isort]
+        command = "isort -y"
+
+        [tool.dephell.flake8]
+        command = "flake8"
+
+        [tool.dephell.pytest]
+        command = "python -m pytest tests/"
+        """,
+    ))
+    config = Config()
+    config.attach({'project': str(temp_path)})
+    command = GenerateContributingCommand(argv=[], config=config)
+    result = command()
+
+    assert result is True
+    assert (temp_path / 'CONTRIBUTING.md').exists()
+    content = (temp_path / 'CONTRIBUTING.md').read_text()
+    assert '## Testing' in content
+    assert '## Style' in content
+    assert 'Sort imports' in content