Skip to content

Commit 4b6ca21

Browse files
llucaxllucax
committed
Add instructions to initialize the docs site
To publish the documentation via GitHub pages it is necessary to do some extra setup that can't be easily automated. This commit add some extra instructions to both the output after generating the templates and the README. Signed-off-by: Leandro Lucarella <[email protected]>
1 parent 7d959e9 commit 4b6ca21

File tree

2 files changed

+113
-10
lines changed

2 files changed

+113
-10
lines changed

‎README.md‎

Lines changed: 93 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -43,20 +43,93 @@ cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecut
4343
This will prompt for the project type, name and other configuration and
4444
generate the whole project for you.
4545

46-
After completing it and fixing the TODOs
47-
you can amend the previous commit using `git commit --amend`
48-
or create a new commit for the changes using `git commit`.
49-
You can make sure linting and tests pass by creating a virtual
50-
environment, installing the development dependencies and running `nox`:
46+
After completing it and fixing the `TODO`s you can amend the previous commit
47+
using `git commit --amend` or create a new commit for the changes using `git
48+
commit`.
49+
50+
### Create the local development environment
51+
52+
To start the development, you need to make sure your environment is correctly
53+
setup. One way to do this is by using a virtual environment and installing all
54+
the dependencies there:
55+
5156
```sh
5257
# requires at least python version 3.11
5358
python3 -m venv .venv
5459
. .venv/bin/activate
55-
pip install .[dev-noxfile]
56-
nox
60+
pip install -e .[dev]
61+
```
62+
63+
This will install you package in [*editable*
64+
mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), so
65+
you can open a python interpreter and import your package modules and pick up
66+
any local changes without the need to reinstall. You can now run tools
67+
directly, like `pytest`.
68+
69+
### Verify the new repository is healthy using `nox`
70+
71+
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:
72+
73+
```sh
74+
pip install -e .[dev-noxfile]
75+
nox --install-only # Set up virtual environments once
76+
nox -R # Run linting and testing reusing the already existing virtual environments
5777
```
5878

59-
## Migrating an existing project
79+
This will only install you package in *editable* mode and the minimum
80+
dependencies to be able to run `nox`, and then run all `nox` default sessions,
81+
which will run linters and tests.
82+
83+
!!! note
84+
85+
It's much faster to use `nox` with `--install-only` once (each time to
86+
change or update dependencies you need to run it again) and then using `nox
87+
-R` to run the sessions without re-creating the virtual environments.
88+
89+
Otherwise `nox` will create many virtual environments each time you run it,
90+
which is **very** slow.
91+
92+
### Verify the generated documentation works
93+
94+
To generate the documentation you can use `mkdocs`:
95+
96+
```sh
97+
pip install .[dev-mkdocs] # Not necessary if you already installed .[dev]
98+
mkdocs serve
99+
```
100+
101+
If the command fails, look at the log warnings and errors and fix them. If it
102+
worked, now there is a local web server serving the documentation, you can
103+
point your browser to Now you can point your browser to
104+
[http://127.0.0.1:8000](/http://127.0.0.1:8000/) to have a look.
105+
106+
!!! info
107+
108+
For API projects `docker` is needed to generate and serve documentation, as
109+
the easiest way to use the [tool to generate the documentation from
110+
`.proto`](https://github.com/pseudomuto/protoc-gen-doc) files is using
111+
`docker`.
112+
113+
### Initialize the GitHub pages website
114+
115+
The generated documentation can be easily published via GitHub pages, and it
116+
will be automatically updated for new pushed and releases, but for that to work
117+
correctly, some initial setup is needed:
118+
119+
```sh
120+
pip install -e .[dev-mkdocs] # Not necessary if you already installed .[dev]
121+
mike deploy --update-aliases next latest # Creates the branch gh-pages locally
122+
mike set-default latest # Makes the latest alias the default version
123+
git push upstream gh-pages # Pushes the new branch upstream so the website is published
124+
```
125+
126+
Then make sure that GitHub pages is enabled in
127+
`https://github.com/<repo-owner>/<repo-name>/settings/pages`.
128+
129+
If all went well, your website should be available soon via
130+
`https://<repo-owner>.github.io//<repo-name>/`.
131+
132+
## Migrate an existing project
60133

61134
The easiest way to migrate an existing project is to just generate a new one
62135
basing all the inputs in the current project metadata and then overwritting the
@@ -86,6 +159,12 @@ git commit -a
86159
Also make sure to **exclude** the `.git/` directory to avoid messing up
87160
with your local git repository.
88161

162+
!!! tip
163+
164+
Please have a look at the follow-up steps listed in the [Start a new
165+
project](#create-the-local-development-environment) section to finish the
166+
setup.
167+
89168
## Update an existing project
90169

91170
To update an existing project you can use the [Cookiecutter *replay
@@ -129,6 +208,12 @@ templates update commit.
129208
Please remember to keep your replay file up to date if you change any
130209
metadata in the project.
131210

211+
!!! tip
212+
213+
Please have a look at the follow-up steps listed in the [Start a new
214+
project](#create-the-local-development-environment) section to finish the
215+
setup.
216+
132217
## Contributing
133218

134219
If you want to know how to build this project and contribute to it, please

‎cookiecutter/hooks/post_gen_project.py‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,12 +66,28 @@ def main() -> None:
6666
print(". .venv/bin/activate")
6767
print("pip install .[dev-noxfile]")
6868
print("nox")
69-
print("# To generate and serve the documentation:")
69+
print()
70+
print("To generate and serve the documentation:")
7071
print("pip install .[dev-mkdocs]")
7172
if cookiecutter.type == "api":
7273
print("# Requires docker")
7374
print("mkdocs serve")
7475
print()
76+
print("To initialize the GitHub pages website:")
77+
print("mike deploy --update-aliases next latest")
78+
print("mike set-default latest")
79+
print("git push upstream gh-pages # or origin if you haven't forked the repo")
80+
print()
81+
print("Make sure that GitHub pages is enabled in your repository settings:")
82+
print(
83+
f"https://github.com/{cookiecutter.github_org}/{cookiecutter.github_repo_name}"
84+
"/settings/pages"
85+
)
86+
print("If all went well, your new website should be available soon at:")
87+
print(
88+
f"https://{cookiecutter.github_org}.github.io/{cookiecutter.github_repo_name}/"
89+
)
90+
print()
7591
if warnings := do_sanity_checks():
7692
for warning in warnings:
7793
warn(warning)
@@ -80,7 +96,9 @@ def main() -> None:
8096
"If you had any issues or find any errors in the generated files, "
8197
"please report them!"
8298
)
83-
note("https://github.com/frequenz-floss/frequenz-repo-config-python/issues/new")
99+
note(
100+
"https://github.com/frequenz-floss/frequenz-repo-config-python/issues/new/choose"
101+
)
84102
print()
85103

86104

0 commit comments

Comments
 (0)