@@ -23,6 +23,9 @@ of Insiders projects in the PyPI index of your choice
2323See [ how to install it] ( https://pawamoy.github.io/pypi-insiders/#installation )
2424and [ how to use it] ( https://pawamoy.github.io/pypi-insiders/#usage ) .
2525
26+ ** We kindly ask that you do not upload the distributions to public registries,
27+ as it is against our [ Terms of use] ( index.md#terms ) .**
28+
2629### with pip (ssh/https)
2730
2831* mkdocstrings-python Insiders* can be installed with ` pip ` [ using SSH] [ using ssh ] :
@@ -58,130 +61,15 @@ pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-pyt
5861> token must be kept secret at all times, as it allows the owner to access your
5962> private repositories.
6063
61- ### with pip (self-hosted)
62-
63- Self-hosting the Insiders package makes it possible to depend on * mkdocstrings-python* normally,
64- while transparently downloading and installing the Insiders version locally.
65- It means that you can specify your dependencies normally, and your contributors without access
66- to Insiders will get the public version, while you get the Insiders version on your machine.
67-
68- WARNING: ** Limitation**
69- With this method, there is no way to force the installation of an Insiders version
70- rather than a public version. If there is a public version that is more recent
71- than your self-hosted Insiders version, the public version will take precedence.
72- Remember to regularly update your self-hosted versions by uploading latest distributions.
73-
74- You can build the distributions for Insiders yourself, by cloning the repository
75- and using [ build] to build the distributions,
76- or you can download them from our [ GitHub Releases] .
77- You can upload these distributions to a private PyPI-like registry
78- ([ Artifactory] , [ Google Cloud] , [ pypiserver] , etc.)
79- with [ Twine] :
80-
81- [ build ] : https://pypi.org/project/build/
82- [ Artifactory ] : https://jfrog.com/help/r/jfrog-artifactory-documentation/pypi-repositories
83- [ Google Cloud ] : https://cloud.google.com/artifact-registry/docs/python
84- [ pypiserver ] : https://pypi.org/project/pypiserver/
85- [ Github Releases ] : https://github.com/pawamoy-insiders/mkdocstrings-python/releases
86- [ Twine ] : https://pypi.org/project/twine/
87-
88- ``` bash
89- # download distributions in ~/dists, then upload with:
90- twine upload --repository-url https://your-private-index.com ~ /dists/*
91- ```
92-
93- <small >You might also need to provide a username and password/token to authenticate against the registry.
94- Please check [ Twine's documentation] [ twine docs ] .</small >
95-
96- [ twine docs ] : https://twine.readthedocs.io/en/stable/
97-
98- You can then configure pip (or other tools) to look for packages into your package index.
99- For example, with pip:
100-
101- ``` bash
102- pip config set global.extra-index-url https://your-private-index.com/simple
103- ```
104-
105- Note that the URL might differ depending on whether your are uploading a package (with Twine)
106- or installing a package (with pip), and depending on the registry you are using (Artifactory, Google Cloud, etc.).
107- Please check the documentation of your registry to learn how to configure your environment.
108-
109- ** We kindly ask that you do not upload the distributions to public registries,
110- as it is against our [ Terms of use] ( index.md#terms ) .**
64+ ### with Git
11165
112- > ? TIP: ** Full example with ` pypiserver ` **
113- > In this example we use [ pypiserver] to serve a local PyPI index.
114- >
115- > ``` bash
116- > pip install --user pypiserver
117- > # or pipx install pypiserver
118- >
119- > # create a packages directory
120- > mkdir -p ~ /.local/pypiserver/packages
121- >
122- > # run the pypi server without authentication
123- > pypi-server run -p 8080 -a . -P . ~ /.local/pypiserver/packages &
124- > ` ` `
125- >
126- > We can configure the credentials to access the server in [` ~/.pypirc`
127- >
128- > [pypirc]: https://packaging.python.org/en/latest/specifications/pypirc/
129- >
130- > ` ` ` " .pypirc"
131- > [distutils]
132- > index-servers =
133- > local
134- >
135- > [local]
136- > repository: http://localhost:8080
137- > username:
138- > password:
139- > ` ` `
140- >
141- > We then clone the Insiders repository, build distributions and upload them to our local server:
142- >
143- > ` ` `
144- > # clone the repository
145- > git clone [email protected] :pawamoy-insiders/mkdocstrings-python146- > cd mkdocstrings-python
147- >
148- > # install build
149- > pip install --user build
150- > # or pipx install build
151- >
152- > # checkout latest tag
153- > git checkout $( git describe --tags --abbrev=0)
154- >
155- > # build the distributions
156- > pyproject-build
157- >
158- > # upload them to our local server
159- > twine upload -r local dist/* --skip-existing
160- > ` ` `
161- >
162- > Finally, we configure pip, and for example [PDM][pdm], to use our local index to find packages:
163- >
164- > ` ` `
165- > pip config set global.extra-index-url http://localhost:8080/simple
166- > pdm config pypi.extra.url http://localhost:8080/simple
167- > ` ` `
168- >
169- > [pdm]: https://pdm.fming.dev/latest/
170- >
171- > Now when running ` ` ,
172- > or resolving dependencies with PDM,
173- > both tools will look into our local index and find the Insiders version.
174- > ** Remember to update your local index regularly! **
175-
176- # ## with git
177-
178- Of course, you can use * mkdocstrings-python Insiders* directly from ` git` :
66+ Of course, you can use * mkdocstrings-python Insiders* directly using Git:
17967
18068```
18169git clone [email protected] :pawamoy-insiders/mkdocstrings-python 18270```
18371
184- When cloning from ` git ` , the package must be installed:
72+ When cloning with Git , the package must be installed:
18573
18674```
18775pip install -e mkdocstrings-python
0 commit comments