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
Copy file name to clipboardExpand all lines: _learn/01-sphinx-python-rtd.md
+19-17Lines changed: 19 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,9 @@
1
1
---
2
2
title: "Set Up Sphinx with Python"
3
-
layout: page
3
+
layout: learn
4
4
image:
5
-
path: /images/learn/sphinx-docs-page.png
6
5
thumbnail: /images/learn/python-logo400x200.png
7
-
caption: "Screenshot from Read the Docs theme"
6
+
caption: "Python and Sphinx"
8
7
---
9
8
10
9
Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from [ReStructured](http://docutils.sourceforge.net/rst.html) text files.
@@ -51,7 +50,7 @@ You also want the latest version of Python 3 available.
51
50
Python 3.7.0
52
51
```
53
52
54
-
1. Check the version set as the default version, the version of Python that is executed when you simply enter `python`. The default version of Python remains a Python 2.7 version.
53
+
1. Check the version set as the default version, the version of Python that is executed when you simply enter `python`. The default version of Python remains a Python 2.7 version.
55
54
56
55
```
57
56
python -V
@@ -60,6 +59,7 @@ You also want the latest version of Python 3 available.
60
59
```
61
60
Python 2.7.15
62
61
```
62
+
63
63
## Set Up Virtual Environment
64
64
65
65
Let's ensure that you know how to create Python Virtual Environments for each version of Python. These [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html) provide a method of creating isolated "environments" where you can work with specific versions of Python along with independent sets of libraries and dependencies.
@@ -103,7 +103,7 @@ Most people use Virtual Environments because it's a recommended practice when wo
103
103
(py3-sphinx) $ pip install sphinx
104
104
```
105
105
106
-
1. To verify that sphinx is installed, run the `sphinx-build` command with the `--help` parameter.
106
+
1. To verify that Sphinx is installed, run the `sphinx-build` command with the `--help` parameter.
107
107
108
108
```
109
109
(py3-sphinx) $ sphinx-build --help
@@ -123,36 +123,38 @@ You can also get familiar with [ReStructured text](http://docutils.sourceforge.n
123
123
```
124
124
1. Answer all the questions from the prompts.
125
125
You can choose enter to pick all the defaults and get a working project in the current directory (`.`).
126
+
>Some notes for the context of this tutorial:
127
+
* You can either use a directory named `_build` within the root path, or have separate `source` and `build` directories, which is the default. To see an example directory structure with a `source` directory, refer to this [justwriteclick/rockthedocs-demo](https://github.com/justwriteclick/rockthedocs-demo) repo on GitHub.
128
+
* When answering the questions, note that you can choose "githubpages set to yes" to create a `.nojekyll` file to publish the document on GitHub pages. In our case, though, our example builds to Read the Docs, so you can use the defaults throughout.
126
129
127
-
Some notes for the context of this tutorial:
128
-
* You can either use a directory named `_build` within the root path, or have separate `source` and `build` directories, which is the default.
129
-
* Note that you can choose "githubpages set to yes" to create a `.nojekyll` file to publish the document on GitHub pages. In our case, though, our example builds to Read the Docs, so you can use the defaults throughout.
130
130
1. Once you have the basics answered, the script creates the necessary files and you can edit those to your liking.
131
131
1. Create a couple of `.rst` files and add skeleton information for starters.
132
132
```
133
133
$ touch source/prerequisites.rst
134
134
$ touch source/about.rst
135
135
```
136
136
1. Edit those new `.rst` files in your favorite text editor.
137
-
1. Now, you can build the docs to see the changes locally:
137
+
1. Now, you can build the docs to see the changes locally. Run this command in the directory with the `conf.py` file:
138
138
```
139
139
$ make html
140
140
```
141
141
1. In your browser, open the `build/html/index.html` file to take a look at your Sphinx site locally. You can also look at `build/html/prerequisites.html` and `build/html/about.html` though they won't be linked to the main page until you add them as a link or in a table of contents entry.
142
-
1. Edit the `source/index.rst` file to include links to the additional pages. Here is an example:
143
-
```
144
-
.. toctree::
145
-
:maxdepth: 2
146
-
:caption: Contents:
142
+
1. Edit the `source/index.rst` file to include links to the additional pages.
143
+
Here is an example:
144
+
```
145
+
.. toctree::
146
+
:maxdepth: 2
147
+
:caption: Contents:
147
148
148
-
about.rst
149
-
prerequisites.rst
150
-
```
149
+
about.rst
150
+
prerequisites.rst
151
+
```
151
152
1. Build again to see these changes locally:
152
153
```
153
154
$ make html
154
155
```
155
156
1. In your browser, refresh the `build/html/index.html` page to see the new Contents with two entries linked.
157
+
156
158
1. Make sure you commit your changes to the Git repository by following the steps in [Working with content in GitHub repositories](https://docslikecode.com/learn/04-add-content-workflow/).
1. Press `Ctrl+C` in the serve terminal to stop the server.
177
177
> ***TIP***
178
178
> Leave the serve terminal open and running. Every time you save changes to a file, it automatically regenerates the site so you can test the output as you write. That said, if you change the `_config.yml` file, you must stop (ctrl-c) and then re-run the serve command to see changes.
Copy file name to clipboardExpand all lines: _learn/03-hugo-go-netlify.md
+4-5Lines changed: 4 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
title: "Set Up Hugo with Go"
3
-
layout: page
3
+
layout: learn
4
4
image:
5
5
path: /images/learn/hugo-docs-page.png
6
6
thumbnail: /images/learn/go-logo400x200.png
@@ -105,11 +105,10 @@ For Hugo, it's important to know that draft pages are only served when using the
105
105
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
106
106
Press Ctrl+C to stop
107
107
```
108
-
109
108
1. Open the **Web Server** URL, `http://localhost:1313/` in your local browser to view the site.
110
-
111
-
1. Press `Ctrl+C` in the server terminal to stop the Hugo server.
112
-
1. You can add your files to a Git commit. Refer to [Working with content in GitHub repositories](https://docslikecode.com/learn/04-add-content-workflow/) for a documentation workflow with your Hugo site.
109
+
110
+
3. Press `Ctrl+C` in the server terminal to stop the Hugo server.
111
+
4. You can add your files to a Git commit. Refer to [Working with content in GitHub repositories](https://docslikecode.com/learn/04-add-content-workflow/) for a documentation workflow with your Hugo site.
0 commit comments