Documentation on Python¶
Writing is an important job not just for writers, but also for researchers. By documenting your academic findings, you can share your works with others and improve your future research. Occasionally, you may have to write academic paper on the scientific journal, but the Internet is a very common and easy to access place to spread out your knowledge or promote your portfolio.
Web writings and HTML¶
However, writing something on the web could be a painful job, if you are not familiar with a very singular language, called HTML. The HTML is a markup language that used in the modern web browsers, and almost every webpages in the world is written in HTML. If you want to become a web developer who makes fancy webpages, web-apps or web services, you may have to learn how to write the HTML code.
But, if you only consider write a document on the web, learning the HTML maybe an annoying job, since the syntax for HTML is very different with other programming languages. For example,
<!DOCTYPE html>
<html>
<body>
<h1>This is the first heading</h1>
<h2>and second heading </h2>
<p>This is the first paragraph,</p>
<p>and this is the second paragraph. You have to make a "p" tag
<b>every time</b> you make another paragraph.
In the paragraph, the new line will be
ignored by a browser.
If you want to make a newline by force, <br>
You can use "br" tag inside of "p" tag.
This is a link to another page. <a href="https://www.w3.org">W3C</a>
</p>
</body>
</html>
As you can see in the above example, the HTML document is structured by
tags which enclosed with inaccessible characters, < >,
and almost every tags in HTML must be paired with the end tag, </ >.
Also the syntax looks very weird at the first time, and even worse is,
you have to learn another language called
CSS to style your
documents.
Markdown¶
A Markdown language can be an antidote for this problem. Technically, a Markdown is not a programming language, but just a plain text. The main goal of the Markdown is to write an easy to read document “as-is”, and also can be converted into HTML easily. Lets see a demo for the Markdown document.
Heading
=======
## This is a sub-heading
### This is a sub-sub-heading
This is a paragraph. If you want to make
another one, just make a blank line.
This is a second paragraph. The new line
will be ignored,
but if you want to make it by force,
just make two spaces
at the end of the line.
You can make an *italic*, **bold** or `monospace` texts.
This is a bullet list
* apples
* oranges
* pears
And numbered list:
1. wash
2. rinse
3. repeat
A [link](http://example.com).
Now, its way better. The Markdown text is very easy to read, and easy to write. Also, since the Markdown text is just a plain text, it is a very portable format which can be imported to another program or services easily. For example, the github.com or bitbucket.org uses markdown syntax to write a “readme” file in the project. (If you write some markdown document in your git repository, and save it with the name of “readme.md”, then you can see your readme file in the bitbucket (or github) webpage.)
To publish your markdown document in the web, you have to convert the markdown file into the HTML. But, this will be done with another program. By writing a markdown text, you don’t need to think about HTML syntax.
reStructuredText¶
reStructuredText is another plaintext markup syntax, which widely used on the Python community to documentating a Python project. For example, the Python document pages were written in reStructuredText with Sphinx converting tool.
Note
This lecture note pages also written in reStructuredText with Sphinx.
The basic syntax for reStructuredText is very similar with markdown.
===============
This is a title
===============
This is the first section
-------------------------
This is a paragraph. new line
will be ignored, and you can start another paragraph
by making a blank line. You can write an
*italic*, **bold**, `monospace` text.
bullet list:
* apple
* oranges
* pears
And numbered list:
1. wash
2. rinse
3. repeat
A `link <http://example.com>`_.
At a glance, the differences between markdown and reStructuredText are hardly noticeable. But the reStructuredText is more functional than markdown, with a variety useful syntax. The markdown is developed only for web writing, but the reStructuredText developed for general technical writing. Therefore, the reStructuredText can be transformed to another format not just for web but also fo LaTex, PDF and more.
To find out differences between markdown and reStructuredText more, please read an article.
Converting tools¶
You can convert markdown or reStructuredText into HTML format, so that you can publish your documents on the web pages. There are so many tools, such as pandoc, docutils, sphinx or pelican.
Sphinx, for example, which used for making this lecture note webpages, can generate a static website from a pack of markdown or reStructuredText. To jumpstart to make a Sphinx webpage, you need to install the Sphinx package.
$ pip3 install sphinx
Yes, the Sphinx is a Python package, so you need to use pip to install it.
After the installation, lets make a “canvas” for webpage.
$ sphinx-quickstart
upon which you will see questions for initial configuration and you answer them.
This will create a source directory with conf.py and a master document called
index.rst. Don’t know what to answer? Don’t be afraid, there are default
answers at the end of the questions, and you can always go with them first and fix them later.
If you open index.rst file, it may look like,
.. test documentation master file, created by
sphinx-quickstart on Fri May 11 00:45:12 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
This will be the the first page of your website, so you can edit this file in reStructuredText format. After editing the document, lets make an HTML file. In terminal, simply type
$ make html
Then, the Sphinx will generate some HTML files in _build/html directory.
If you open the index.html file on your web browser (such as Chrome, Safari or Firefox)
then you can see an web-formatted documents.
If you want to see more tutorials, find this Youtube video.