diff --git a/Markdown/Example_Markdown.md b/Markdown/Example_Markdown.md new file mode 100644 index 0000000000000000000000000000000000000000..f1d7ef1a5bd6516c4ed4d83ed43a0a789e123f9c --- /dev/null +++ b/Markdown/Example_Markdown.md @@ -0,0 +1,329 @@ + +Markdown File Example +===================== + +Contents +======== + +* [Overview](#overview) +* [This is what you can do](#this-is-what-you-can-do) + * [Create Markdown files](#create-markdown-files) + * [Create Headers](#create-headers) + * [Table of Contents](#table-of-contents) + * [Paragraph and Text Format](#paragraph-and-text-format) + * [Create a Table](#create-a-table) + * [Create Links](#create-links) + * [Create Lists](#create-lists) + * [Add images](#add-images) + * [Add HTML images](#add-html-images) + +# Overview + + +This is an example of markdown file created using mdutils python package. In this example you are going to see how to create a markdown file using this library. Moreover, you're finding the available features which makes easy the creation of this type of files while you are running Python code. + +**IMPORTANT:** some features available on this library have no effect with the GitHub Markdown CSS. Some of them are: coloring text, centering text... + + +# This is what you can do + +## Create Markdown files + + +``create_md_file()`` is the last command that has to be called. + +```python +import Mdutils + + +mdFile = MdUtils(file_name='Example_Markdown',title='Markdown File Example') +mdFile.create_md_file() +``` +## Create Headers + + +Using ``new_header`` method you can create headers of different levels depending on the style. There are two available styles: 'atx' and 'setext'. The first one has til 6 different header levels. Atx's levels 1 and 2 are automatically added to the table of contents unless the parameter ``add_table_of_contents`` is set to 'n'. The 'setext' style only has two levelsof headers. + +```python +mdFile.new_header(level=1, title='Atx Header 1') +mdFile.new_header(level=2, title='Atx Header 2') +mdFile.new_header(level=3, title='Atx Header 3') +mdFile.new_header(level=4, title='Atx Header 4') +mdFile.new_header(level=5, title='Atx Header 5') +mdFile.new_header(level=6, title='Atx Header 6') +``` +# Atx Header 1 + +## Atx Header 2 + +### Atx Header 3 + +#### Atx Header 4 + +##### Atx Header 5 + +###### Atx Header 6 + + +```python +mdFile.new_header(level=1, title='Setext Header 1', style='setext') +mdFile.new_header(level=2, title='Setext Header 2', style='setext') +``` +Setext Header 1 +=============== + +Setext Header 2 +--------------- + + + +## Table of Contents + + +If you have defined some headers of level 1 and 2, you can create a table of contents invoking the following command (Normally, the method will be called at the end of the code before calling ``create_md_file()``) + +```python +mdFile.new_table_of_contents(table_title='Contents', depth=2) +``` +## Paragraph and Text Format + + +mdutils allows you to create paragraph, line breaks or simply write text: +### New Paragraph Method + + +```python +mdFile.new_paragraph("Using ``new_paragraph`` method you can very easily add a new paragraph" + " This example of paragraph has been added using this method. Moreover," + "``new_paragraph`` method make your live easy because it can give format" + " to the text. Lets see an example:") +``` + +Using ``new_paragraph`` method you can very easily add a new paragraph on your markdown file. This example of paragraph has been added using this method. Moreover, ``new_paragraph`` method make your live easy because it can give format to the text. Lets see an example: + +```python +mdFile.new_paragraph("This is an example of text in which has been added color, bold and italics text.", bold_italics_code='bi', color='purple') +``` + +***<font color="purple">This is an example of text in which has been added color, bold and italics text.</font>*** +### New Line Method + + +``mdutils`` has a method which can create new line breaks. Lets see it. + +```python +mdFile.new_line("This is an example of line break which has been created with ``new_line`` method.") +``` +This is an example of line break which has been created with ``new_line`` method. + +As ``new_paragraph``, ``new_line`` allows users to give format to text using ``bold_italics_code`` and ``color`` parameters: + +```python +mdFile.new_line("This is an inline code which contains bold and italics text and it is centered", bold_italics_code='cib', align='center') +``` +***<center>``This is an inline code which contains bold and italics text and it is centered``</center>*** +### Write Method + + +``write`` method writes text in a markdown file without jump lines ``'\n'`` and as ``new_paragraph`` and ``new_line``, you can give format to text using the arguments ``bold_italics_code``, ``color`` and ``align``: + +```python +mdFile.write("The following text has been written with ``write`` method. You can use markdown directives to write:" + "**bold**, _italics_, ``inline_code``... or ") +mdFile.write("use the following available parameters: \n") +``` + +The following text has been written with ``write`` method. You can use markdown directives to write: **bold**, _italics_, ``inline_code``... or use the following available parameters: + + +```python +mdFile.write(' \n') +mdFile.write('bold_italics_code', bold_italics_code='bic') +mdFile.write(' \n') +mdFile.write('Text color', color='green') +mdFile.write(' \n') +mdFile.write('Align Text to center', align='center') +``` +***``bold_italics_code``*** +<font color="green">Text color</font> +<center>Align Text to center</center> + +## Create a Table + + +The library implements a method called ``new_table`` that can create tables using a list of strings. This method only needs: the number of rows and columns that your table must have. Optionally you can align the content of the table using the parameter ``text_align`` + +```python +list_of_strings = ["Items", "Descriptions", "Data"] +for x in range(5): + list_of_strings.extend(["Item " + str(x), "Description Item " + str(x), str(x)]) +mdFile.new_line() +mdFile.new_table(columns=3, rows=6, text=list_of_strings, text_align='center') +``` + +|Items|Descriptions|Data| +| :---: | :---: | :---: | +|Item 0|Description Item 0|0| +|Item 1|Description Item 1|1| +|Item 2|Description Item 2|2| +|Item 3|Description Item 3|3| +|Item 4|Description Item 4|4| + +## Create Links + +### Create inline links + + +``new_inline_link`` method allows you to create a link of the style: ``[mdutils](https://github.com/didix21/mdutils)``. + + +Moreover, you can add bold, italics or code in the link text. Check the following examples: + + +```python +mdFile.new_line(' - Inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils')) +mdFile.new_line(' - Bold inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='b') +mdFile.new_line(' - Italics inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='i') +mdFile.new_line(' - Code inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='i') +mdFile.new_line(' - Bold italics code inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='cbi') +mdFile.new_line(' - Another inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils') + +``` + - Inline link: [mdutils](https://github.com/didix21/mdutils) + - Bold inline link: [**mdutils**](https://github.com/didix21/mdutils) + - Italics inline link: [*mdutils*](https://github.com/didix21/mdutils) + - Code inline link: [``mdutils``](https://github.com/didix21/mdutils) + - Bold italics code inline link: [***``mdutils``***](https://github.com/didix21/mdutils) + - Another inline link: [https://github.com/didix21/mdutils](https://github.com/didix21/mdutils) +### Create reference links + + +``new_reference_link`` method allows you to create a link of the style: ``[mdutils][1]``. All references will be added at the end of the markdown file automatically as: + + +```python +[1]: https://github.com/didix21/mdutils +``` + +Lets check some examples: + + +```python +mdFile.write('\n - Reference link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='mdutils', reference_tag='1') +mdFile.write('\n - Reference link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='another reference', reference_tag='md') +mdFile.write('\n - Bold link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='Bold reference', reference_tag='bold', bold_italics_code='b') +mdFile.write('\n - Italics link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='Bold reference', reference_tag='italics', bold_italics_code='i') + +``` + - Reference link: [mdutils][1] + - Reference link: [another reference][md] + - Bold link: [**Bold reference**][bold] + - Italics link: [*Italics reference*][italics] +## Create Lists + +### Create unordered lists + + +You can add Mark down unordered list using ``mdFile.new_list(items, marked_with)``. Lets check an example: + +``` +items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', ['Item 4.1', 'Item 4.2', ['Item 4.2.1', 'Item 4.2.2'], 'Item 4.3', ['Item 4.3.1']], 'Item 5'] +mdFile.new_list(items) + +``` +- Item 1 +- Item 2 +- Item 3 +- Item 4 + - Item 4.1 + - Item 4.2 + - Item 4.2.1 + - Item 4.2.2 + - Item 4.3 + - Item 4.3.1 +- Item 5 + +### Create ordered lists + + +You can add ordered ones easily, too: ``mdFile.new_list(items, marked_with='1')`` +1. Item 1 +2. Item 2 +3. Item 3 +4. Item 4 + 1. Item 4.1 + 2. Item 4.2 + 1. Item 4.2.1 + 2. Item 4.2.2 + 3. Item 4.3 + 1. Item 4.3.1 +5. Item 5 + + +Moreover, you can add mixed list, for example: + +``` +items = ['Item 1', 'Item 2', ['1. Item 2.1', '2. Item 2.2'], 'Item 3'] +mdFile.new_list(items) + +``` +- Item 1 +- Item 2 + 1. Item 2.1 + 2. Item 2.2 +- Item 3 + + +Maybe you want to replace the default hyphen ``-`` by a ``+`` or ``*`` then you can do: ``mdFile.new_list(items, marked_with='*')``. +## Add images + +### Inline Images + + +You can add inline images using ``new_inline_image`` method. Method will return: ``[image](../path/to/your/image.png)``. Check the following example: + +``` +mdFile.new_line(mdFile.new_inline_image(text='snow trees', path='./doc/source/images/photo-of-snow-covered-trees.jpg')) +``` + +### Reference Images + + +You can add inline images using ``new_reference_image`` method. Method will return: ``[image][im]``. Check the following example: + +``` +mdFile.new_line(mdFile.new_reference_image(text='snow trees', path='./doc/source/images/photo-of-snow-covered-trees.jpg', reference_tag='im')) +``` +![snow trees][im] +## Add HTML images + +### Change size to images + + +With ``Html.image`` you can change size of images in a markdown file. For example you can dothe following for changing width: ``mdFile.new_paragraph(Html.image(path=path, size='200'))`` + +<img src="./doc/source/images/sunset.jpg" width="200"/> + +Or maybe only want to change height: ``mdFile.new_paragraph(Html.image(path=path, size='x300'))`` + +<img src="./doc/source/images/sunset.jpg" height="300"/> + +Or change width and height: ``mdFile.new_paragraph(Html.image(path=path, size='300x300'))`` + +<img src="./doc/source/images/sunset.jpg" width="300" height="300"/> + +### Align images + + +Html.image allow to align images, too. For example you can run: ``mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center'))`` + +<p align="center"> + <img src="./doc/source/images/sunset.jpg" width="300" height="200"/> +</p> + + +[1]: https://github.com/didix21/mdutils +[bold]: https://github.com/didix21/mdutils +[im]: ./doc/source/images/photo-of-snow-covered-trees.jpg +[italics]: https://github.com/didix21/mdutils +[md]: https://github.com/didix21/mdutils diff --git a/Markdown/mdutil_example.py b/Markdown/mdutil_example.py new file mode 100644 index 0000000000000000000000000000000000000000..6a7068d23dddaf9abdbd5baf49e5cb3024c8cbb0 --- /dev/null +++ b/Markdown/mdutil_example.py @@ -0,0 +1,326 @@ +# Python +# +# This file implements an example. +# +# This file is part of mdutils. https://github.com/didix21/mdutils +# +# MIT License: (C) 2018 DÃdac Coll +# +# Usage: +# > python3 mdutil_example.py # create example file in markdown format +# > retext Example_Markdown.md # view file in markdown format + + +from mdutils.mdutils import MdUtils +from mdutils import Html + +mdFile = MdUtils(file_name='Example_Markdown', title='Markdown File Example') + +mdFile.new_header(level=1, title='Overview') # style is set 'atx' format by default. + +mdFile.new_paragraph("This is an example of markdown file created using mdutils python package. In this example you " + "are going to see how to create a markdown file using this library. Moreover, you're " + "finding the available features which makes easy the creation of this type of files while you " + "are running Python code.") +mdFile.new_paragraph("**IMPORTANT:** some features available on this library have no effect with the GitHub Markdown " + "CSS. Some of them are: coloring text, centering text...") +mdFile.new_paragraph() + +# Available Features +mdFile.new_header(level=1, title="This is what you can do") + +# ******************************************************************************************************************** +# ***************************************************** Markdown ***************************************************** +# ******************************************************************************************************************** +mdFile.new_header(level=2, title="Create Markdown files") +mdFile.new_paragraph("``create_md_file()`` is the last command that has to be called.") +mdFile.insert_code("import Mdutils\n" + "\n" + "\n" + "mdFile = MdUtils(file_name=\'Example_Markdown\',title=\'Markdown File Example\')\n" + "mdFile.create_md_file()", language='python') + +# ******************************************************************************************************************** +# ***************************************************** Headers ****************************************************** +# ******************************************************************************************************************** +mdFile.new_header(level=2, title="Create Headers") +mdFile.new_paragraph("Using ``new_header`` method you can create headers of different levels depending on the style. " + "There are two available styles: 'atx' and 'setext'. The first one has til 6 different header " + "levels. Atx's levels 1 and 2 are automatically added to the table of contents unless the " + "parameter ``add_table_of_contents`` is set to 'n'. The 'setext' style only has two levels" + "of headers.") + +mdFile.insert_code("mdFile.new_header(level=1, title='Atx Header 1')\n" + "mdFile.new_header(level=2, title='Atx Header 2')\n" + "mdFile.new_header(level=3, title='Atx Header 3')\n" + "mdFile.new_header(level=4, title='Atx Header 4')\n" + "mdFile.new_header(level=5, title='Atx Header 5')\n" + "mdFile.new_header(level=6, title='Atx Header 6')", language='python') + +mdFile.new_header(level=1, title='Atx Header 1', add_table_of_contents='n') +mdFile.new_header(level=2, title='Atx Header 2', add_table_of_contents='n') +mdFile.new_header(level=3, title='Atx Header 3') +mdFile.new_header(level=4, title='Atx Header 4') +mdFile.new_header(level=5, title='Atx Header 5') +mdFile.new_header(level=6, title='Atx Header 6') + +mdFile.insert_code("mdFile.new_header(level=1, title='Setext Header 1', style='setext')\n" + "mdFile.new_header(level=2, title='Setext Header 2', style='setext')", language='python') + +mdFile.new_header(level=1, title='Setext Header 1', style='setext', add_table_of_contents='n') +mdFile.new_header(level=2, title='Setext Header 2', style='setext', add_table_of_contents='n') +mdFile.new_paragraph() # Add two jump lines + +# ******************************************************************************************************************** +# ******************************************** Create a table of contents ******************************************** +# ******************************************************************************************************************** +mdFile.new_header(level=2, title='Table of Contents') +mdFile.new_paragraph("If you have defined some headers of level 1 and 2, you can create a table of contents invoking " + "the following command (Normally, the method will be called at the end of the code before calling " + "``create_md_file()``)") +mdFile.insert_code("mdFile.new_table_of_contents(table_title='Contents', depth=2)", language='python') + +# ******************************************************************************************************************** +# ******************************************** Paragraph and Text format ********************************************* +# ******************************************************************************************************************** +mdFile.new_header(level=2, title="Paragraph and Text Format") +mdFile.new_paragraph("mdutils allows you to create paragraph, line breaks or simply write text:") +# *************************************************** Paragraph ****************************************************** +mdFile.new_header(3, "New Paragraph Method") + +mdFile.insert_code("mdFile.new_paragraph(\"Using ``new_paragraph`` method you can very easily add a new paragraph\" \n" + "\t\t\t\t\t \" This example of paragraph has been added using this method. Moreover,\"\n" + "\t\t\t\t\t \"``new_paragraph`` method make your live easy because it can give format\" \n" + "\t\t\t\t\t \" to the text. Lets see an example:\")", language='python') + +mdFile.new_paragraph("Using ``new_paragraph`` method you can very easily add a new paragraph on your markdown file. " + "This example of paragraph has been added using this method. Moreover, ``new_paragraph`` method " + "make your live easy because it can give format to the text. Lets see an example:") + +mdFile.insert_code("mdFile.new_paragraph(\"This is an example of text in which has been added color, " + "bold and italics text.\", bold_italics_code='bi', color='purple')", language='python') + +mdFile.new_paragraph("This is an example of text in which has been added color, bold and italics text.", + bold_italics_code='bi', color='purple') +# ************************************************* New Line ********************************************************* +mdFile.new_header(3, "New Line Method") + +mdFile.new_paragraph("``mdutils`` has a method which can create new line breaks. Lets see it.") +mdFile.insert_code("mdFile.new_line(\"This is an example of line break which has been created with ``new_line`` " + "method.\")", language='python') +mdFile.new_line("This is an example of line break which has been created with ``new_line`` method.") +mdFile.new_paragraph("As ``new_paragraph``, ``new_line`` allows users to give format to text using " + "``bold_italics_code`` and ``color`` parameters:") + +mdFile.insert_code("mdFile.new_line(\"This is an inline code which contains bold and italics text and it is centered\"," + " bold_italics_code='cib', align='center')", language='python') + +mdFile.new_line("This is an inline code which contains bold and italics text and it is centered", + bold_italics_code='cib', align='center') +# ************************************************** write ********************************************************** +mdFile.new_header(3, "Write Method") +mdFile.new_paragraph("``write`` method writes text in a markdown file without jump lines ``'\\n'`` and as " + "``new_paragraph`` and ``new_line``, you can give format to text using the arguments " + "``bold_italics_code``, ``color`` and ``align``: ") + +mdFile.insert_code("mdFile.write(\"The following text has been written with ``write`` method. You can use markdown " + "directives to write:\"\n" + "\t\t\t \"**bold**, _italics_, ``inline_code``... or \")\n" + "mdFile.write(\"use the following available parameters: \\n\")", language='python') + +mdFile.write("\n\nThe following text has been written with ``write`` method. You can use markdown directives to write: " + "**bold**, _italics_, ``inline_code``... or ") +mdFile.write("use the following available parameters: \n") + +mdFile.insert_code("mdFile.write(' \\n')\n" + "mdFile.write('bold_italics_code', bold_italics_code='bic')\n" + "mdFile.write(' \\n')\n" + "mdFile.write('Text color', color='green')\n" + "mdFile.write(' \\n')\n" + "mdFile.write('Align Text to center', align='center')", language='python') + +mdFile.write(' \n') +mdFile.write('bold_italics_code', bold_italics_code='bic') +mdFile.write(' \n') +mdFile.write('Text color', color='green') +mdFile.write(' \n') +mdFile.write('Align Text to center', align='center') +mdFile.write(' \n') + +# ******************************************************************************************************************** +# ************************************************* Create a Table *************************************************** +# ******************************************************************************************************************** +mdFile.new_header(2, "Create a Table") +mdFile.new_paragraph("The library implements a method called ``new_table`` that can create tables using a list of " + "strings. This method only needs: the number of rows and columns that your table must have. " + "Optionally you can align the content of the table using the parameter ``text_align``") + +mdFile.insert_code("list_of_strings = [\"Items\", \"Descriptions\", \"Data\"]\n" + "for x in range(5):\n" + "\tlist_of_strings.extend([\"Item \" + str(x), \"Description Item \" + str(x), str(x)])\n" + "mdFile.new_line()\n" + "mdFile.new_table(columns=3, rows=6, text=list_of_strings, text_align='center')", language='python') + +list_of_strings = ["Items", "Descriptions", "Data"] +for x in range(5): + list_of_strings.extend(["Item " + str(x), "Description Item " + str(x), str(x)]) +mdFile.new_line() +mdFile.new_table(columns=3, rows=6, text=list_of_strings, text_align='center') + +# ******************************************************************************************************************** +# ************************************************** Create Link ***************************************************** +# ******************************************************************************************************************** + +mdFile.new_header(2, "Create Links") + +# *********************************************** Inline link ******************************************************** + +mdFile.new_header(3, "Create inline links") + +link = "https://github.com/didix21/mdutils" +text = "mdutils" + +mdFile.new_paragraph("``new_inline_link`` method allows you to create a link of the style: " + "``[mdutils](https://github.com/didix21/mdutils)``.\n") +mdFile.new_paragraph("Moreover, you can add bold, italics or code in the link text. Check the following examples: \n") + +mdFile.insert_code("mdFile.new_line(' - Inline link: '" + " + mdFile.new_inline_link(link='{}', text='{}')) \n".format(link, text) + + "mdFile.new_line(' - Bold inline link: ' " + "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='b') \n".format(link, text) + + "mdFile.new_line(' - Italics inline link: ' " + "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='i') \n".format(link, text) + + "mdFile.new_line(' - Code inline link: ' " + "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='i') \n".format(link, text) + + "mdFile.new_line(' - Bold italics code inline link: ' " + "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='cbi') \n".format(link, text) + + "mdFile.new_line(' - Another inline link: ' + mdFile.new_inline_link(link='{}') \n".format(link), + language='python') + +mdFile.new_line(' - Inline link: ' + mdFile.new_inline_link(link=link, text=text)) +mdFile.new_line(' - Bold inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='b')) +mdFile.new_line(' - Italics inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='i')) +mdFile.new_line(' - Code inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='c')) +mdFile.new_line( + ' - Bold italics code inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='cbi')) +mdFile.new_line(' - Another inline link: ' + mdFile.new_inline_link(link=link)) + +# *********************************************** Reference link ****************************************************** +mdFile.new_header(3, "Create reference links") + +mdFile.new_paragraph("``new_reference_link`` method allows you to create a link of the style: " + "``[mdutils][1]``. All references will be added at the end of the markdown file automatically as: \n") + +mdFile.insert_code("[1]: https://github.com/didix21/mdutils", language="python") +mdFile.new_paragraph("Lets check some examples: \n") + +link = "https://github.com/didix21/mdutils" + +mdFile.insert_code("mdFile.write('\\n - Reference link: ' " + "+ mdFile.new_reference_link(link='{}', text='mdutils', reference_tag='1')\n".format(link) + + "mdFile.write('\\n - Reference link: ' " + "+ mdFile.new_reference_link(link='{}', text='another reference', reference_tag='md')\n".format( + link) + + "mdFile.write('\\n - Bold link: ' " + "+ mdFile.new_reference_link(link='{}', text='Bold reference', reference_tag='bold', bold_italics_code='b')\n".format( + link) + + "mdFile.write('\\n - Italics link: ' " + "+ mdFile.new_reference_link(link='{}', text='Bold reference', reference_tag='italics', bold_italics_code='i')\n".format( + link), + language="python") + +mdFile.write("\n - Reference link: " + mdFile.new_reference_link(link=link, text='mdutils', reference_tag='1')) +mdFile.write( + "\n - Reference link: " + mdFile.new_reference_link(link=link, text='another reference', reference_tag='md')) +mdFile.write("\n - Bold link: " + mdFile.new_reference_link(link=link, text='Bold reference', reference_tag='bold', + bold_italics_code='b')) +mdFile.write( + "\n - Italics link: " + mdFile.new_reference_link(link=link, text='Italics reference', reference_tag='italics', + bold_italics_code='i')) + +# ******************************************************************************************************************** +# ************************************************** Create Lists ***************************************************** +# ******************************************************************************************************************** +mdFile.new_header(2, "Create Lists") +# *********************************************** Unordered Lists ****************************************************** +mdFile.new_header(3, "Create unordered lists") +mdFile.new_paragraph( + "You can add Mark down unordered list using ``mdFile.new_list(items, marked_with)``. Lets check an example: ") +items = ["Item 1", "Item 2", "Item 3", "Item 4", ["Item 4.1", "Item 4.2", ["Item 4.2.1", "Item 4.2.2"], + "Item 4.3", ["Item 4.3.1"]], "Item 5"] +mdFile.insert_code(f'items = {items}\n' + f'mdFile.new_list(items)\n') +mdFile.new_list(items=items) + +# *********************************************** Ordered Lists ****************************************************** +mdFile.new_header(3, "Create ordered lists") +mdFile.new_paragraph("You can add ordered ones easily, too: ``mdFile.new_list(items, marked_with='1')``") +mdFile.new_list(items=items, marked_with='1') + +mdFile.new_paragraph("Moreover, you can add mixed list, for example: ") +items = ["Item 1", "Item 2", ["1. Item 2.1", "2. Item 2.2"], "Item 3"] +mdFile.insert_code(f'items = {items}\n' + f'mdFile.new_list(items)\n') +mdFile.new_list(items) +mdFile.new_paragraph("Maybe you want to replace the default hyphen ``-`` by a ``+`` or ``*`` then you can do: " + "``mdFile.new_list(items, marked_with='*')``.") + +# ******************************************************************************************************************** +# ************************************************** Add Images ****************************************************** +# ******************************************************************************************************************** + +mdFile.new_header(2, "Add images") + +# *********************************************** Inline Image ******************************************************* + +image_text = "snow trees" +path = "./doc/source/images/photo-of-snow-covered-trees.jpg" + +mdFile.new_header(3, "Inline Images") + +mdFile.new_paragraph("You can add inline images using ``new_inline_image`` method. Method will return: " + "``[image](../path/to/your/image.png)``. Check the following example: ") +mdFile.insert_code("mdFile.new_line(mdFile.new_inline_image(text='{}', path='{}'))".format(image_text, path)) +mdFile.new_line(mdFile.new_inline_image(text=image_text, path=path)) + +# *********************************************** Reference Image ***************************************************** +mdFile.new_header(3, "Reference Images") +mdFile.new_paragraph("You can add inline images using ``new_reference_image`` method. Method will return: " + "``[image][im]``. Check the following example: ") +mdFile.insert_code( + "mdFile.new_line(mdFile.new_reference_image(text='{}', path='{}', reference_tag='im'))".format(image_text, path)) +mdFile.new_line(mdFile.new_reference_image(text=image_text, path=path, reference_tag='im')) + +# ************************************************* Html Image ******************************************************* + +mdFile.new_header(2, "Add HTML images") + +# *********************************************** Size Image ******************************************************* + +mdFile.new_header(3, "Change size to images") +path = "./doc/source/images/sunset.jpg" + +mdFile.new_paragraph("With ``Html.image`` you can change size of images in a markdown file. For example you can do" + "the following for changing width: ``mdFile.new_paragraph(Html.image(path=path, size='200'))``") + +mdFile.new_paragraph(Html.image(path=path, size='200')) + +mdFile.new_paragraph( + "Or maybe only want to change height: ``mdFile.new_paragraph(Html.image(path=path, size='x300'))``") +mdFile.new_paragraph(Html.image(path=path, size='x300')) + +mdFile.new_paragraph("Or change width and height: ``mdFile.new_paragraph(Html.image(path=path, size='300x300'))``") +mdFile.new_paragraph(Html.image(path=path, size='300x300')) +mdFile.write('\n') + +# *********************************************** Align Image ******************************************************* + +mdFile.new_header(3, "Align images") +mdFile.new_paragraph("Html.image allow to align images, too. For example you can run: " + "``mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center'))``") + +mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center')) + +# Create a table of contents +mdFile.new_table_of_contents(table_title='Contents', depth=2) +mdFile.create_md_file() diff --git a/Markdown/readme_markdown.txt b/Markdown/readme_markdown.txt new file mode 100644 index 0000000000000000000000000000000000000000..e0b6c6a0eb42244eec6f0a4d861ed02f2741fac3 --- /dev/null +++ b/Markdown/readme_markdown.txt @@ -0,0 +1,116 @@ +------------------------------------------------------------------------------- +-- +-- Copyright 2021 +-- ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/> +-- P.O.Box 2, 7990 AA Dwingeloo, The Netherlands +-- +-- Licensed under the Apache License, Version 2.0 (the "License"); +-- you may not use this file except in compliance with the License. +-- You may obtain a copy of the License at +-- +-- http://www.apache.org/licenses/LICENSE-2.0 +-- +-- Unless required by applicable law or agreed to in writing, software +-- distributed under the License is distributed on an "AS IS" BASIS, +-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +-- See the License for the specific language governing permissions and +-- limitations under the License. +-- +------------------------------------------------------------------------------- +-- +-- Author: E. Kooistra +-- Purpose: Help for using Markdown language + +Contents + +1) Markdown viewer +2) Markdown generator +3) Markdown language help + + + +1) Markdown viewer + +Use e.g.: +- Linux 'retext' as markdown editor and previewer. + . Use Preview menu for live preview +- https://typora.io, nice but seems too advanced and therefore not compatible + with other viewers. + . Markdown is a simple and not exact defined document structure language, + therefore it seems better to keep it simple and only use what is + supported by most viewers, e.g. by retext and the gitlab viewer. + + + +2) Markdown generator + +- Python3 --> import mdutil # markdown writer en reader +- 1) Mark down viewer + +> Python3 mdutil_example.py # --> 1) Example_Markdown.md +> retext Example_Markdown.md + + + +3) Markdown language help + +Markdown is not well defined, so it is not always sure that the text will +appear as expected in each viewer. For example retext and gitlab viewer differ. +Therefore it is important to keep the markdown simple and to accept that +readable text is good enough, rather than to strive for a specific layout. + +Text will wrap. + +Backslash is escape chararcter. + +# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +##### Heading 5 +###### Heading 6 + +Horizontal rules three or more of ***, ___, --- + +*italic* +_italic_ +**bold** +__bold__ +**bold and _bolditalic_** combined +`boxed` +~~strike through~~ + +```vhdl +Text in ascii VHDL style for GitLab +``` + +Block quotes (alinea with an indent bar): +> Block text will wrap + +Unordered list using *, -, +, indent >= 1 space +* Main item 1 +* Main item 2 + * sub item 2a use 2 trailing spaces for return inside paragraph + * sub item 2b + +Ordered list +1. Main item 1 +2. Main item 2 + 2.1 sub item 2a + 2.2 sub item 2b + +Images + + +![Logo][image1] + +[image1]:web link to image file + +Links: +[ASTRON]:https://www.astron.nl + +Table: +|col1 | col2| Col3 | column titles +|---|:---:|--:| >= 3 dashes, colon for left, center, right align +| row text | row text | row text| +| row text | row text | row text|