Skip to content

Commit 71d8dad

Browse files
JonoYangJonoYang
committed
Update READMEs
Signed-off-by: Jono Yang <jyang@nexb.com>
1 parent 8583d7f commit 71d8dad

File tree

3 files changed

+305
-155
lines changed

3 files changed

+305
-155
lines changed

‎README.rst

Lines changed: 1 addition & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -9,161 +9,7 @@ our existing ones as well.
99

1010
Usage
1111
=====
12-
A brand new project
13-
-------------------
14-
.. code-block:: bash
15-
16-
git init my-new-repo
17-
cd my-new-repo
18-
git pull git@github.com:nexB/skeleton
19-
20-
# Create the new repo on GitHub, then update your remote
21-
git remote set-url origin git@github.com:nexB/your-new-repo.git
22-
23-
From here, you can make the appropriate changes to the files for your specific project.
24-
25-
Update an existing project
26-
---------------------------
27-
.. code-block:: bash
28-
29-
cd my-existing-project
30-
git remote add skeleton git@github.com:nexB/skeleton
31-
git fetch skeleton
32-
git merge skeleton/main --allow-unrelated-histories
33-
34-
This is also the workflow to use when updating the skeleton files in any given repository.
35-
36-
Customizing
37-
-----------
38-
39-
You typically want to perform these customizations:
40-
41-
- remove or update the src/README.rst and tests/README.rst files
42-
- set project info and dependencies in setup.cfg
43-
- check the configure and configure.bat defaults
44-
45-
Initializing a project
46-
----------------------
47-
48-
All projects using the skeleton will be expected to pull all of it dependencies
49-
from thirdparty.aboutcode.org/pypi or the local thirdparty directory, using
50-
requirements.txt and/or requirements-dev.txt to determine what version of a
51-
package to collect. By default, PyPI will not be used to find and collect
52-
packages from.
53-
54-
In the case where we are starting a new project where we do not have
55-
requirements.txt and requirements-dev.txt and whose dependencies are not yet on
56-
thirdparty.aboutcode.org/pypi, we run the following command after adding and
57-
customizing the skeleton files to your project:
58-
59-
.. code-block:: bash
60-
61-
./configure --init
62-
63-
This will initialize the virtual environment for the project, pull in the
64-
dependencies from PyPI and add them to the virtual environment.
65-
66-
Generating requirements.txt and requirements-dev.txt
67-
----------------------------------------------------
68-
69-
After the project has been initialized, we can generate the requirements.txt and
70-
requirements-dev.txt files.
71-
72-
Ensure the virtual environment is enabled.
73-
74-
.. code-block:: bash
75-
76-
source venv/bin/activate
77-
78-
To generate requirements.txt:
79-
80-
.. code-block:: bash
81-
82-
python etc/scripts/gen_requirements.py -s venv/lib/python<version>/site-packages/
83-
84-
Replace \<version\> with the version number of the Python being used, for example: ``venv/lib/python3.6/site-packages/``
85-
86-
To generate requirements-dev.txt after requirements.txt has been generated:
87-
88-
.. code-block:: bash
89-
./configure --init --dev
90-
python etc/scripts/gen_requirements_dev.py -s venv/lib/python<version>/site-packages/
91-
92-
Note: on Windows, the ``site-packages`` directory is located at ``venv\Lib\site-packages\``
93-
94-
.. code-block:: bash
95-
96-
python .\\etc\\scripts\\gen_requirements.py -s .\\venv\\Lib\\site-packages\\
97-
.\configure --init --dev
98-
python .\\etc\\scripts\\gen_requirements_dev.py -s .\\venv\\Lib\\site-packages\\
99-
100-
Collecting and generating ABOUT files for dependencies
101-
------------------------------------------------------
102-
103-
Ensure that the dependencies used by ``etc/scripts/bootstrap.py`` are installed:
104-
105-
.. code-block:: bash
106-
107-
pip install -r etc/scripts/requirements.txt
108-
109-
Once we have requirements.txt and requirements-dev.txt, we can fetch the project
110-
dependencies as wheels and generate ABOUT files for them:
111-
112-
.. code-block:: bash
113-
114-
python etc/scripts/bootstrap.py -r requirements.txt -r requirements-dev.txt --with-deps
115-
116-
There may be issues with the generated ABOUT files, which will have to be
117-
corrected. You can check to see if your corrections are valid by running:
118-
119-
.. code-block:: bash
120-
121-
python etc/scripts/check_thirdparty.py -d thirdparty
122-
123-
Once the wheels are collected and the ABOUT files are generated and correct,
124-
upload them to thirdparty.aboutcode.org/pypi by placing the wheels and ABOUT
125-
files from the thirdparty directory to the pypi directory at
126-
https://github.com/nexB/thirdparty-packages
127-
128-
129-
Usage after project initialization
130-
----------------------------------
131-
132-
Once the ``requirements.txt`` and ``requirements-dev.txt`` have been generated
133-
and the project dependencies and their ABOUT files have been uploaded to
134-
thirdparty.aboutcode.org/pypi, you can configure the project without using the
135-
``--init`` option.
136-
137-
If the virtual env for the project becomes polluted, or you would like to remove
138-
it, use the ``--clean`` option:
139-
140-
.. code-block:: bash
141-
142-
./configure --clean
143-
144-
Then you can run ``./configure`` again to set up the project virtual environment.
145-
146-
To set up the project for development use:
147-
148-
.. code-block:: bash
149-
150-
./configure --dev
151-
152-
To update the project dependencies (adding, removing, updating packages, etc.),
153-
update the dependencies in ``setup.cfg``, then run:
154-
155-
.. code-block:: bash
156-
157-
./configure --clean # Remove existing virtual environment
158-
./configure --init # Create project virtual environment, pull in new dependencies
159-
source venv/bin/activate # Ensure virtual environment is activated
160-
python etc/scripts/gen_requirements.py -s venv/lib/python<version>/site-packages/ # Regenerate requirements.txt
161-
python etc/scripts/gen_requirements_dev.py -s venv/lib/python<version>/site-packages/ # Regenerate requirements-dev.txt
162-
pip install -r etc/scripts/requirements.txt # Install dependencies needed by etc/scripts/bootstrap.py
163-
python etc/scripts/bootstrap.py -r requirements.txt -r requirements-dev.txt --with-deps # Collect dependency wheels and their ABOUT files
164-
165-
Ensure that the generated ABOUT files are valid, then take the dependency wheels
166-
and ABOUT files and upload them to thirdparty.aboutcode.org/pypi.
12+
Usage instructions can be found in ``docs/skeleton-usage.rst``.
16713

16814
Release Notes
16915
=============

‎docs/skeleton-usage.rst

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
Usage
2+
=====
3+
A brand new project
4+
-------------------
5+
.. code-block:: bash
6+
7+
git init my-new-repo
8+
cd my-new-repo
9+
git pull git@github.com:nexB/skeleton
10+
11+
# Create the new repo on GitHub, then update your remote
12+
git remote set-url origin git@github.com:nexB/your-new-repo.git
13+
14+
From here, you can make the appropriate changes to the files for your specific project.
15+
16+
Update an existing project
17+
---------------------------
18+
.. code-block:: bash
19+
20+
cd my-existing-project
21+
git remote add skeleton git@github.com:nexB/skeleton
22+
git fetch skeleton
23+
git merge skeleton/main --allow-unrelated-histories
24+
25+
This is also the workflow to use when updating the skeleton files in any given repository.
26+
27+
Customizing
28+
-----------
29+
30+
You typically want to perform these customizations:
31+
32+
- remove or update the src/README.rst and tests/README.rst files
33+
- set project info and dependencies in setup.cfg
34+
- check the configure and configure.bat defaults
35+
36+
Initializing a project
37+
----------------------
38+
39+
All projects using the skeleton will be expected to pull all of it dependencies
40+
from thirdparty.aboutcode.org/pypi or the local thirdparty directory, using
41+
requirements.txt and/or requirements-dev.txt to determine what version of a
42+
package to collect. By default, PyPI will not be used to find and collect
43+
packages from.
44+
45+
In the case where we are starting a new project where we do not have
46+
requirements.txt and requirements-dev.txt and whose dependencies are not yet on
47+
thirdparty.aboutcode.org/pypi, we run the following command after adding and
48+
customizing the skeleton files to your project:
49+
50+
.. code-block:: bash
51+
52+
./configure --init
53+
54+
This will initialize the virtual environment for the project, pull in the
55+
dependencies from PyPI and add them to the virtual environment.
56+
57+
Generating requirements.txt and requirements-dev.txt
58+
----------------------------------------------------
59+
60+
After the project has been initialized, we can generate the requirements.txt and
61+
requirements-dev.txt files.
62+
63+
Ensure the virtual environment is enabled.
64+
65+
.. code-block:: bash
66+
67+
source venv/bin/activate
68+
69+
To generate requirements.txt:
70+
71+
.. code-block:: bash
72+
73+
python etc/scripts/gen_requirements.py -s venv/lib/python<version>/site-packages/
74+
75+
Replace \<version\> with the version number of the Python being used, for example: ``venv/lib/python3.6/site-packages/``
76+
77+
To generate requirements-dev.txt after requirements.txt has been generated:
78+
79+
.. code-block:: bash
80+
./configure --init --dev
81+
python etc/scripts/gen_requirements_dev.py -s venv/lib/python<version>/site-packages/
82+
83+
Note: on Windows, the ``site-packages`` directory is located at ``venv\Lib\site-packages\``
84+
85+
.. code-block:: bash
86+
87+
python .\\etc\\scripts\\gen_requirements.py -s .\\venv\\Lib\\site-packages\\
88+
.\configure --init --dev
89+
python .\\etc\\scripts\\gen_requirements_dev.py -s .\\venv\\Lib\\site-packages\\
90+
91+
Collecting and generating ABOUT files for dependencies
92+
------------------------------------------------------
93+
94+
Ensure that the dependencies used by ``etc/scripts/bootstrap.py`` are installed:
95+
96+
.. code-block:: bash
97+
98+
pip install -r etc/scripts/requirements.txt
99+
100+
Once we have requirements.txt and requirements-dev.txt, we can fetch the project
101+
dependencies as wheels and generate ABOUT files for them:
102+
103+
.. code-block:: bash
104+
105+
python etc/scripts/bootstrap.py -r requirements.txt -r requirements-dev.txt --with-deps
106+
107+
There may be issues with the generated ABOUT files, which will have to be
108+
corrected. You can check to see if your corrections are valid by running:
109+
110+
.. code-block:: bash
111+
112+
python etc/scripts/check_thirdparty.py -d thirdparty
113+
114+
Once the wheels are collected and the ABOUT files are generated and correct,
115+
upload them to thirdparty.aboutcode.org/pypi by placing the wheels and ABOUT
116+
files from the thirdparty directory to the pypi directory at
117+
https://github.com/nexB/thirdparty-packages
118+
119+
120+
Usage after project initialization
121+
----------------------------------
122+
123+
Once the ``requirements.txt`` and ``requirements-dev.txt`` have been generated
124+
and the project dependencies and their ABOUT files have been uploaded to
125+
thirdparty.aboutcode.org/pypi, you can configure the project without using the
126+
``--init`` option.
127+
128+
If the virtual env for the project becomes polluted, or you would like to remove
129+
it, use the ``--clean`` option:
130+
131+
.. code-block:: bash
132+
133+
./configure --clean
134+
135+
Then you can run ``./configure`` again to set up the project virtual environment.
136+
137+
To set up the project for development use:
138+
139+
.. code-block:: bash
140+
141+
./configure --dev
142+
143+
To update the project dependencies (adding, removing, updating packages, etc.),
144+
update the dependencies in ``setup.cfg``, then run:
145+
146+
.. code-block:: bash
147+
148+
./configure --clean # Remove existing virtual environment
149+
./configure --init # Create project virtual environment, pull in new dependencies
150+
source venv/bin/activate # Ensure virtual environment is activated
151+
python etc/scripts/gen_requirements.py -s venv/lib/python<version>/site-packages/ # Regenerate requirements.txt
152+
python etc/scripts/gen_requirements_dev.py -s venv/lib/python<version>/site-packages/ # Regenerate requirements-dev.txt
153+
pip install -r etc/scripts/requirements.txt # Install dependencies needed by etc/scripts/bootstrap.py
154+
python etc/scripts/bootstrap.py -r requirements.txt -r requirements-dev.txt --with-deps # Collect dependency wheels and their ABOUT files
155+
156+
Ensure that the generated ABOUT files are valid, then take the dependency wheels
157+
and ABOUT files and upload them to thirdparty.aboutcode.org/pypi.

0 commit comments

Comments
 (0)