.. _ch03-python-documentation: ======================= 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. .. _ch03-html: 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, .. code-block:: html

This is the first heading

and second heading

This is the first paragraph,

and this is the second paragraph. You have to make a "p" tag every time 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,
You can use "br" tag inside of "p" tag. This is a link to another page. W3C

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. .. _ch03-md: 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. .. code-block:: md 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). ![Image](Image_icon.png) 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. .. _ch03-rst: 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. .. code-block:: rst =============== 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 `_. 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. .. code-block:: console $ 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. .. code-block:: console $ 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, .. code-block:: rst .. 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 .. code-block:: console $ 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 `_.