You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This will prompt for the project type, name and other configuration and
43
-
generate the whole project for you.
42
+
This command will prompt you for the project type, name, and other
43
+
configuration options, and it will generate the entire project for you.
44
44
45
-
After completing it and fixing the `TODO`s you can amend the previous commit
46
-
using `git commit --amend` or create a new commit for the changes using `git
47
-
commit`.
45
+
After completing the project and fixing the `TODO`s, you can either amend the
46
+
previous commit using `git commit --amend` or create a new commit for the
47
+
changes using `git commit`.
48
48
49
49
### Create the local development environment
50
50
51
-
To start the development, you need to make sure your environment is correctly
52
-
setup. One way to do this is by using a virtual environment and installing all
53
-
the dependencies there:
51
+
To start development, you need to make sure your environment is correctly set
52
+
up. One way to do this is by using a virtual environment and installing all the
53
+
dependencies there:
54
54
55
55
```sh
56
-
# requires at least python version 3.11
56
+
# requires at least Python version 3.11
57
57
python3 -m venv .venv
58
58
. .venv/bin/activate
59
59
pip install -e .[dev]
60
60
```
61
61
62
-
This will install you package in [*editable*
62
+
This will install your package in [*editable*
63
63
mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), so
64
-
you can open a python interpreter and import your package modules and pick up
65
-
any local changes without the need to reinstall. You can now run tools
64
+
you can open a Python interpreter and import your package modules, picking up
65
+
any local changes without the need to reinstall. Now you can run tools
66
66
directly, like `pytest`.
67
67
68
68
### Verify the new repository is healthy using `nox`
69
69
70
-
If you prefer to keep your virtual enviroment cleaner and avoid installing development dependencies, you can also use `nox` to create isolated environments for you:
70
+
If you prefer to keep your virtual environment cleaner and avoid installing
71
+
development dependencies, you can also use `nox` to create isolated
72
+
environments:
71
73
72
74
```sh
73
75
pip install -e .[dev-noxfile]
74
76
nox --install-only # Set up virtual environments once
75
-
nox -R # Run linting and testing reusing the already existing virtual environments
77
+
nox -R # Run linting and testing reusing the existing virtual environments
76
78
```
77
79
78
-
This will only install you package in *editable* mode and the minimum
79
-
dependencies to be able to run `nox`, and then run all `nox` default sessions,
80
-
which will run linters and tests.
80
+
This will only install your package in *editable* mode and the minimum
81
+
dependencies required to run `nox`. It will then run all `nox` default
82
+
sessions, which include running linters and tests.
81
83
82
84
!!! note
83
85
84
-
It's much faster to use `nox` with `--install-only` once (each time to
85
-
change or update dependencies you need to run it again) and then using `nox
86
-
-R` to run the sessions without re-creating the virtual environments.
86
+
It's much faster to use `nox` with `--install-only` once (each time you
87
+
change or update dependencies, you need to run it again) and then use `nox
88
+
-R` to run the sessions without recreating the virtual environments.
87
89
88
-
Otherwise `nox` will create many virtual environments each time you run it,
89
-
which is **very** slow.
90
+
Otherwise, `nox` will create many virtual environments each time you run
91
+
it, which is **very** slow.
90
92
91
93
### Verify the generated documentation works
92
94
93
-
To generate the documentation you can use `mkdocs`:
95
+
To generate the documentation, you can use `mkdocs`:
94
96
95
97
```sh
96
98
pip install .[dev-mkdocs] # Not necessary if you already installed .[dev]
97
99
mkdocs serve
98
100
```
99
101
100
-
If the command fails, look at the log warnings and errors and fix them. If it
101
-
worked, now there is a local web server serving the documentation, you can
102
-
point your browser to Now you can point your browser to
103
-
[http://127.0.0.1:8000](/http://127.0.0.1:8000/) to have a look.
102
+
If the command fails, look at the log warnings and errors and fix them. If it
103
+
worked, now there is a local web server serving the documentation. You can
104
+
point your browser to [http://127.0.0.1:8000](http://127.0.0.1:8000) to have
105
+
a look.
104
106
105
107
!!! info
106
108
107
-
For API projects `docker` is needed to generate and serve documentation, as
108
-
the easiest way to use the [tool to generate the documentation from
109
-
`.proto`](https://github.com/pseudomuto/protoc-gen-doc) files is using
109
+
For API projects, `docker` is needed to generate and serve documentation,
110
+
as the easiest way to use the [tool to generate the documentation from
111
+
`.proto` files](https://github.com/pseudomuto/protoc-gen-doc) is using
110
112
`docker`.
111
113
112
-
### Initialize the GitHub pages website
114
+
### Initialize the GitHub Pages website
113
115
114
-
The generated documentation can be easily published via GitHub pages, and it
115
-
will be automatically updated for new pushed and releases, but for that to work
116
-
correctly, some initial setup is needed:
116
+
The generated documentation can be easily published via GitHub Pages, and it
117
+
will be automatically updated for new pushes and releases. However, some
118
+
initial setup is needed for it to work correctly:
117
119
118
120
```sh
119
121
pip install -e .[dev-mkdocs] # Not necessary if you already installed .[dev]
120
122
mike deploy --update-aliases next latest # Creates the branch gh-pages locally
121
123
mike set-default latest # Makes the latest alias the default version
122
-
git push upstream gh-pages # Pushes the new branch upstream so the website is published
124
+
git push upstream gh-pages # Pushes the new branch upstream to publish the website
0 commit comments