Skip to content

Commit a9ff98c

Browse files
ceciherrceciherr
committed
deploy: 8a2491f 
1 parent aa1db84 commit a9ff98c

File tree

4 files changed

+331
-2
lines changed

4 files changed

+331
-2
lines changed

‎_sources/git.rst.txt

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,169 @@
11
GIT tips
22
========
33

4+
Getting Started with Git and GitHub
5+
-----------------------------------
46

7+
1. Set Up Your SSH Key
8+
______________________
9+
10+
To securely connect with GitHub, you'll need to add your SSH key to your GitHub account. Here you can find how to `add your public key <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_ .
11+
12+
2. Clone a GitHub Repository
13+
____________________________
14+
15+
Navigate to the directory where you want to download the repository, then use the :code:`git clone` command:
16+
17+
.. code:: bash
18+
19+
git clone [email protected]:psm-compute/psm-compute.github.io.git
20+
21+
This command will create a copy of the repository in your specified directory.
22+
23+
3. Check the Status of Your Repository
24+
______________________________________
25+
26+
After cloning, it's a good practice to check the status of your repository to see if there are any changes:
27+
28+
.. code:: bash
29+
30+
git status
31+
32+
4. Create and Switch to a New Branch
33+
____________________________________
34+
35+
To make changes without affecting the main branch, create a new branch and switch to it. Let's make a test updating `README.md` file.
36+
37+
.. code:: bash
38+
39+
git branch update_readme
40+
git checkout update_readme
41+
42+
43+
5. Edit Files and Stage Changes
44+
_______________________________
45+
46+
Make the necessary edits to your files. For example, to edit the `README.md` file, use a text editor like `vi`:
47+
48+
.. code:: bash
49+
50+
vi README.md
51+
52+
After editing, check the status again to see the changes:
53+
54+
.. code:: bash
55+
56+
git status
57+
58+
Stage the changes to prepare them for commit:
59+
60+
.. code:: bash
61+
62+
git add README.md
63+
64+
6. Commit and Push Changes
65+
__________________________
66+
67+
Commit your changes with a descriptive message:
68+
69+
.. code:: bash
70+
71+
git commit -m "Test change README.md"
72+
73+
Next, push your changes to GitHub. If it's the first time you're pushing from this branch, you'll need to set the upstream branch:
74+
75+
.. code:: bash
76+
77+
git push
78+
79+
If you encounter an error, you'll typically need to set the upstream for the branch:
80+
81+
.. code:: bash
82+
83+
git push --set-upstream origin update_readme
84+
85+
8. Create a Pull Request
86+
________________________
87+
88+
Finally, open your web browser and navigate to the GitHub page for this project:
89+
90+
`<https://github.com/psm-compute/psm-compute.github.io>`_
91+
92+
After pushing your changes, you should see a message indicating the recent pushes. Click on **"Compare & pull request"**.
93+
94+
On the right side of the page, select your reviewers, and add a description if needed. This will create a pull request for your changes to be reviewed and merged.
95+
96+
97+
7. Delete the Branch Locally (Optional)
98+
_______________________________________
99+
100+
If you no longer need the branch locally, you can delete it:
101+
102+
.. code:: bash
103+
104+
git branch -d update_readme
105+
106+
107+
Modifying the HTML Webpage
108+
---------------------------
109+
110+
1. Compile the HTML Webpage Locally
111+
____________________________________
112+
113+
To compile the HTML files locally, navigate to the parent directory of your project and run:
114+
115+
.. code-block:: bash
116+
117+
make html
118+
119+
This command will generate the HTML files for your webpage.
120+
121+
**Troubleshooting:**
122+
123+
- If the ``make html`` command fails, you might need to install the necessary dependencies first. You can do this by running:
124+
125+
.. code-block:: bash
126+
127+
pip install -r requirements.txt
128+
129+
2. View the Compiled HTML
130+
__________________________
131+
132+
Once the compilation is successful, you can view the HTML files by navigating to the ``docs/build/html`` directory. Open the files in this folder with your preferred web browser to see your webpage.
133+
134+
3. Modify the Documentation
135+
____________________________
136+
137+
**Important:**
138+
139+
- **Never modify files directly in the** ``html`` **folder.**
140+
- Always make changes in the ``docs/source`` folder, which contains the source files used to generate the HTML.
141+
142+
**Steps for Modifying Content:**
143+
144+
1. **Create a New** ``.rst`` **File:**
145+
146+
If you need to add new content, you can create a new ``.rst`` file in the ``docs/source`` directory. Use an existing file, such as ``oar.rst``, as a template for the new file.
147+
148+
- **Formatting Tips:** For guidance on formatting ``.rst`` files, refer to `appropriate documentation <https://developer.lsst.io/restructuredtext/style.html>`_.
149+
150+
151+
2. **Update the** ``index.rst`` **File:**
152+
153+
After adding or modifying ``.rst`` files, update the ``index.rst`` file to include your new content in the table of contents or navigation structure.
154+
155+
4. Re-compile the HTML Webpage
156+
_______________________________
157+
158+
Once you've made your changes, recompile the HTML files by running ``make html`` again from the parent directory (``docs``), where the ``make.bat`` file is located:
159+
160+
.. code-block:: bash
161+
162+
make html
163+
164+
This will regenerate the HTML files with your latest modifications.
165+
166+
5. Commit and Push Changes
167+
__________________________
168+
169+
After confirming your changes are reflected in the compiled HTML, it's time to commit and push your changes to the repository. For detailed instructions on how to commit and push changes, see see `Getting Started with Git and GitHub <#getting-started-with-git-and-github>`_.

‎git.html

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,135 @@
113113
<main role="main" id="main">
114114
<section id="git-tips">
115115
<h1>GIT tips<a class="headerlink" href="#git-tips" title="Link to this heading"></a></h1>
116+
<section id="getting-started-with-git-and-github">
117+
<h2>Getting Started with Git and GitHub<a class="headerlink" href="#getting-started-with-git-and-github" title="Link to this heading"></a></h2>
118+
<section id="set-up-your-ssh-key">
119+
<h3>1. Set Up Your SSH Key<a class="headerlink" href="#set-up-your-ssh-key" title="Link to this heading"></a></h3>
120+
<p>To securely connect with GitHub, you’ll need to add your SSH key to your GitHub account. Here you can find how to <a class="reference external" href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account">add your public key</a> .</p>
121+
</section>
122+
<section id="clone-a-github-repository">
123+
<h3>2. Clone a GitHub Repository<a class="headerlink" href="#clone-a-github-repository" title="Link to this heading"></a></h3>
124+
<p>Navigate to the directory where you want to download the repository, then use the <code class="code docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span></code> command:</p>
125+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>[email protected]:psm-compute/psm-compute.github.io.git
126+
</pre></div>
127+
</div>
128+
<p>This command will create a copy of the repository in your specified directory.</p>
129+
</section>
130+
<section id="check-the-status-of-your-repository">
131+
<h3>3. Check the Status of Your Repository<a class="headerlink" href="#check-the-status-of-your-repository" title="Link to this heading"></a></h3>
132+
<p>After cloning, it’s a good practice to check the status of your repository to see if there are any changes:</p>
133+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>status
134+
</pre></div>
135+
</div>
136+
</section>
137+
<section id="create-and-switch-to-a-new-branch">
138+
<h3>4. Create and Switch to a New Branch<a class="headerlink" href="#create-and-switch-to-a-new-branch" title="Link to this heading"></a></h3>
139+
<p>To make changes without affecting the main branch, create a new branch and switch to it. Let’s make a test updating <cite>README.md</cite> file.</p>
140+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>branch<span class="w"> </span>update_readme
141+
git<span class="w"> </span>checkout<span class="w"> </span>update_readme
142+
</pre></div>
143+
</div>
144+
</section>
145+
<section id="edit-files-and-stage-changes">
146+
<h3>5. Edit Files and Stage Changes<a class="headerlink" href="#edit-files-and-stage-changes" title="Link to this heading"></a></h3>
147+
<p>Make the necessary edits to your files. For example, to edit the <cite>README.md</cite> file, use a text editor like <cite>vi</cite>:</p>
148+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>vi<span class="w"> </span>README.md
149+
</pre></div>
150+
</div>
151+
<p>After editing, check the status again to see the changes:</p>
152+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>status
153+
</pre></div>
154+
</div>
155+
<p>Stage the changes to prepare them for commit:</p>
156+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>add<span class="w"> </span>README.md
157+
</pre></div>
158+
</div>
159+
</section>
160+
<section id="commit-and-push-changes">
161+
<h3>6. Commit and Push Changes<a class="headerlink" href="#commit-and-push-changes" title="Link to this heading"></a></h3>
162+
<p>Commit your changes with a descriptive message:</p>
163+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">&quot;Test change README.md&quot;</span>
164+
</pre></div>
165+
</div>
166+
<p>Next, push your changes to GitHub. If it’s the first time you’re pushing from this branch, you’ll need to set the upstream branch:</p>
167+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>push
168+
</pre></div>
169+
</div>
170+
<p>If you encounter an error, you’ll typically need to set the upstream for the branch:</p>
171+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>push<span class="w"> </span>--set-upstream<span class="w"> </span>origin<span class="w"> </span>update_readme
172+
</pre></div>
173+
</div>
174+
</section>
175+
<section id="create-a-pull-request">
176+
<h3>8. Create a Pull Request<a class="headerlink" href="#create-a-pull-request" title="Link to this heading"></a></h3>
177+
<p>Finally, open your web browser and navigate to the GitHub page for this project:</p>
178+
<p><a class="reference external" href="https://github.com/psm-compute/psm-compute.github.io">https://github.com/psm-compute/psm-compute.github.io</a></p>
179+
<p>After pushing your changes, you should see a message indicating the recent pushes. Click on <strong>“Compare &amp; pull request”</strong>.</p>
180+
<p>On the right side of the page, select your reviewers, and add a description if needed. This will create a pull request for your changes to be reviewed and merged.</p>
181+
</section>
182+
<section id="delete-the-branch-locally-optional">
183+
<h3>7. Delete the Branch Locally (Optional)<a class="headerlink" href="#delete-the-branch-locally-optional" title="Link to this heading"></a></h3>
184+
<p>If you no longer need the branch locally, you can delete it:</p>
185+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>branch<span class="w"> </span>-d<span class="w"> </span>update_readme
186+
</pre></div>
187+
</div>
188+
</section>
189+
</section>
190+
<section id="modifying-the-html-webpage">
191+
<h2>Modifying the HTML Webpage<a class="headerlink" href="#modifying-the-html-webpage" title="Link to this heading"></a></h2>
192+
<section id="compile-the-html-webpage-locally">
193+
<h3>1. Compile the HTML Webpage Locally<a class="headerlink" href="#compile-the-html-webpage-locally" title="Link to this heading"></a></h3>
194+
<p>To compile the HTML files locally, navigate to the parent directory of your project and run:</p>
195+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>html
196+
</pre></div>
197+
</div>
198+
<p>This command will generate the HTML files for your webpage.</p>
199+
<p><strong>Troubleshooting:</strong></p>
200+
<ul>
201+
<li><p>If the <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> command fails, you might need to install the necessary dependencies first. You can do this by running:</p>
202+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
203+
</pre></div>
204+
</div>
205+
</li>
206+
</ul>
207+
</section>
208+
<section id="view-the-compiled-html">
209+
<h3>2. View the Compiled HTML<a class="headerlink" href="#view-the-compiled-html" title="Link to this heading"></a></h3>
210+
<p>Once the compilation is successful, you can view the HTML files by navigating to the <code class="docutils literal notranslate"><span class="pre">docs/build/html</span></code> directory. Open the files in this folder with your preferred web browser to see your webpage.</p>
211+
</section>
212+
<section id="modify-the-documentation">
213+
<h3>3. Modify the Documentation<a class="headerlink" href="#modify-the-documentation" title="Link to this heading"></a></h3>
214+
<p><strong>Important:</strong></p>
215+
<ul class="simple">
216+
<li><p><strong>Never modify files directly in the</strong> <code class="docutils literal notranslate"><span class="pre">html</span></code> <strong>folder.</strong></p></li>
217+
<li><p>Always make changes in the <code class="docutils literal notranslate"><span class="pre">docs/source</span></code> folder, which contains the source files used to generate the HTML.</p></li>
218+
</ul>
219+
<p><strong>Steps for Modifying Content:</strong></p>
220+
<ol class="arabic">
221+
<li><p><strong>Create a New</strong> <code class="docutils literal notranslate"><span class="pre">.rst</span></code> <strong>File:</strong></p>
222+
<p>If you need to add new content, you can create a new <code class="docutils literal notranslate"><span class="pre">.rst</span></code> file in the <code class="docutils literal notranslate"><span class="pre">docs/source</span></code> directory. Use an existing file, such as <code class="docutils literal notranslate"><span class="pre">oar.rst</span></code>, as a template for the new file.</p>
223+
<ul class="simple">
224+
<li><p><strong>Formatting Tips:</strong> For guidance on formatting <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files, refer to <a class="reference external" href="https://developer.lsst.io/restructuredtext/style.html">appropriate documentation</a>.</p></li>
225+
</ul>
226+
</li>
227+
<li><p><strong>Update the</strong> <code class="docutils literal notranslate"><span class="pre">index.rst</span></code> <strong>File:</strong></p>
228+
<p>After adding or modifying <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files, update the <code class="docutils literal notranslate"><span class="pre">index.rst</span></code> file to include your new content in the table of contents or navigation structure.</p>
229+
</li>
230+
</ol>
231+
</section>
232+
<section id="re-compile-the-html-webpage">
233+
<h3>4. Re-compile the HTML Webpage<a class="headerlink" href="#re-compile-the-html-webpage" title="Link to this heading"></a></h3>
234+
<p>Once you’ve made your changes, recompile the HTML files by running <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> again from the parent directory (<code class="docutils literal notranslate"><span class="pre">docs</span></code>), where the <code class="docutils literal notranslate"><span class="pre">make.bat</span></code> file is located:</p>
235+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>html
236+
</pre></div>
237+
</div>
238+
<p>This will regenerate the HTML files with your latest modifications.</p>
239+
</section>
240+
<section id="id1">
241+
<h3>5. Commit and Push Changes<a class="headerlink" href="#id1" title="Link to this heading"></a></h3>
242+
<p>After confirming your changes are reflected in the compiled HTML, it’s time to commit and push your changes to the repository. For detailed instructions on how to commit and push changes, see see <a class="reference external" href="#getting-started-with-git-and-github">Getting Started with Git and GitHub</a>.</p>
243+
</section>
244+
</section>
116245
</section>
117246

118247
</main>
@@ -123,6 +252,37 @@ <h1>GIT tips<a class="headerlink" href="#git-tips" title="Link to this heading">
123252
</nav>
124253
</div>
125254

255+
<nav class="col-12 col-lg-3 pb-4">
256+
<div class="sticky-top toc page-toc" aria-labelledby="page-toc-heading">
257+
<p class="font-weight-bold" id="page-toc-heading">Page contents</p>
258+
<ul>
259+
<li><a class="reference internal" href="#">GIT tips</a><ul>
260+
<li><a class="reference internal" href="#getting-started-with-git-and-github">Getting Started with Git and GitHub</a><ul>
261+
<li><a class="reference internal" href="#set-up-your-ssh-key">1. Set Up Your SSH Key</a></li>
262+
<li><a class="reference internal" href="#clone-a-github-repository">2. Clone a GitHub Repository</a></li>
263+
<li><a class="reference internal" href="#check-the-status-of-your-repository">3. Check the Status of Your Repository</a></li>
264+
<li><a class="reference internal" href="#create-and-switch-to-a-new-branch">4. Create and Switch to a New Branch</a></li>
265+
<li><a class="reference internal" href="#edit-files-and-stage-changes">5. Edit Files and Stage Changes</a></li>
266+
<li><a class="reference internal" href="#commit-and-push-changes">6. Commit and Push Changes</a></li>
267+
<li><a class="reference internal" href="#create-a-pull-request">8. Create a Pull Request</a></li>
268+
<li><a class="reference internal" href="#delete-the-branch-locally-optional">7. Delete the Branch Locally (Optional)</a></li>
269+
</ul>
270+
</li>
271+
<li><a class="reference internal" href="#modifying-the-html-webpage">Modifying the HTML Webpage</a><ul>
272+
<li><a class="reference internal" href="#compile-the-html-webpage-locally">1. Compile the HTML Webpage Locally</a></li>
273+
<li><a class="reference internal" href="#view-the-compiled-html">2. View the Compiled HTML</a></li>
274+
<li><a class="reference internal" href="#modify-the-documentation">3. Modify the Documentation</a></li>
275+
<li><a class="reference internal" href="#re-compile-the-html-webpage">4. Re-compile the HTML Webpage</a></li>
276+
<li><a class="reference internal" href="#id1">5. Commit and Push Changes</a></li>
277+
</ul>
278+
</li>
279+
</ul>
280+
</li>
281+
</ul>
282+
283+
</div>
284+
</nav>
285+
126286
</div>
127287
</div>
128288
</div>

‎index.html

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,11 @@ <h1>Unofficial PSM tips and tricks<a class="headerlink" href="#unofficial-psm-ti
124124
<li class="toctree-l2"><a class="reference internal" href="oar.html#submit-multiple-jobs">Submit multiple jobs</a></li>
125125
</ul>
126126
</li>
127-
<li class="toctree-l1"><a class="reference internal" href="git.html">GIT tips</a></li>
127+
<li class="toctree-l1"><a class="reference internal" href="git.html">GIT tips</a><ul>
128+
<li class="toctree-l2"><a class="reference internal" href="git.html#getting-started-with-git-and-github">Getting Started with Git and GitHub</a></li>
129+
<li class="toctree-l2"><a class="reference internal" href="git.html#modifying-the-html-webpage">Modifying the HTML Webpage</a></li>
130+
</ul>
131+
</li>
128132
</ul>
129133
</div>
130134
</section>

0 commit comments

Comments
 (0)