or
or
By clicking below, you agree to our terms of service.
New to HackMD? Sign up
Syntax | Example | Reference | |
---|---|---|---|
# Header | Header | 基本排版 | |
- Unordered List |
|
||
1. Ordered List |
|
||
- [ ] Todo List |
|
||
> Blockquote | Blockquote |
||
**Bold font** | Bold font | ||
*Italics font* | Italics font | ||
~~Strikethrough~~ | |||
19^th^ | 19th | ||
H~2~O | H2O | ||
++Inserted text++ | Inserted text | ||
==Marked text== | Marked text | ||
[link text](https:// "title") | Link | ||
 | Image | ||
`Code` | Code |
在筆記中貼入程式碼 | |
```javascript var i = 0; ``` |
|
||
:smile: | ![]() |
Emoji list | |
{%youtube youtube_id %} | Externals | ||
$L^aT_eX$ | LaTeX | ||
:::info This is a alert area. ::: |
This is a alert area. |
On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?
Please give us some advice and help us improve HackMD.
Do you want to remove this version name and description?
Syncing
xxxxxxxxxx
Intro to Sphinx for Python Documentation
https://hackmd.io/@melissawm/SkjCa3OkO#/
https://github.com/melissawm/minimalsphinx
https://numpy.org/doc/stable
First things first
Image by David Whittaker
What is documentation?
Image from Divio
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →What is Sphinx?
reStructuredText
, and outputs HTML.conf.py
On an empty project
sphinx
(for example,pip install sphinx
)conf.py
file and initial directory structure by runningconf.py
,index.rst
and any other files you wish_build/html/
)The reStructuredText format
sphinx-quickstart
, anindex.rst
file is created*text*
for emphasis (italics),**text**
for strong emphasis (boldface)``text``
for code samples.The reStructuredText format II
Example: index.rst
Auto-documenting a Python package
Sphinx supports the inclusion of docstrings from your modules with an extension called autodoc.
The
conf.py
fileYou can then document whole classes or even modules automatically, using member options for the auto directives, like
Other extensions
Example: NumPy docs
A Pull Request to the NumPy documentation
https://numpy.org/contribute/
With thanks to Fatma Tarlaci!
In our Quickstart guide, there is a typo in the following sentence:
We'll fix this now.
Steps
Most of the steps are described in this page of the NumPy documentation.
upstream
remoteNow we can build NumPy. Using pip+venv:
Finally, we can build the documentation:
Submit a Pull Request
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →Jupyter notebooks
Final thoughts
Obrigada!
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →@melissawm