Skip to content

Instantly share code, notes, and snippets.

@epogrebnyak

epogrebnyak/asciidoc_example.adoc

Last active February 19, 2022 18:44
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save epogrebnyak/593873598a511f9a799bc2743db28b9e to your computer and use it in GitHub Desktop.
Save epogrebnyak/593873598a511f9a799bc2743db28b9e to your computer and use it in GitHub Desktop.
Download ZIP
Tools, editors, etc
Raw
asciidoc_example.adoc

AsciiDoc tutorial

Table of Contents

AsciiDoc fills an important gap between markdown and reStructuredText

AsciiDoc seems not as common as markdown. Google lists just about 400 000 citations about it, as opposed to 16 million for markdown. However, AsciiDoc allows some of reStructuredText functionality (eg <include> directives) while preserving most of the simplicity of markdown.

Why AsciiDoc better than markdown:

  • ✓ sane logic for headers

  • ✓ easy table of contents (toc)

  • ✓ include directive

  • ✓ bibliographic references!

  • ✓ color!

  • ✓ comments

  • ✓ integrates with github via .adoc extension

  • ✓ allows some mixins of markdown

Missed from markdown:

  • ❏ intuitive links notation [text](http:\...)

Not fully functional:

  • ❏ math not rendering on Atom editor or github

Links used

Official site is a bit messy, while asciidoctor.org does a better job of explaining . Some practical experiences with github flavour of AsciiDoc are also a nice read.

Using references in text

Can use extended references:

The Pragmatic Programmer [pp] should be required reading for all developers. To learn all about design patterns, refer to the book by the “Gang of Four” [2].

  • [pp] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [2] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

Better tables

Tables are one of the most intricate, yet refined areas of the AsciiDoc syntax.

Table 1. An example table
Col 1 Col 2 Col 3

1

Item 1

a

2

Item 2

b

3

Item 3

c

6

Three items

d
Table 2. Title for table 1
Name of Column 1 Name of Column 2 Name of Column 3

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

Questions:

  • Can use markdown tables? .rst tables?

  • VS code shortcuts for creating and formatting tables

Other cool stuff

Quotes

It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness…​
— Charles Dickens
A Tale of Two Cities

Using awesome fonts?

Just as Note has a symbol, these symbols/emoji may appear elsewhere in text.

Definition list

CPU

The brain of the computer.

Hard drive

Permanent storage for operating system and/or user files.

RAM

Temporarily stores information the CPU uses during operation.

Admonition

Note

An admonition block may contain complex content.

Another paragraph.

Things not fully working

Color

This text is red, but not on github ;(

Lists

A list

  • one

  • two

  • three

Note
 Can I get 1.1, 1.2, etc in a numbered list? TODO: fill issue

  1. abc

    1. xxx

    2. yyy

Math

STEM math does not render in Atom. See asciidoctor/atom-asciidoc-preview#94

\$sqrt(4) = 2\$
\$sqrt(4) = 2\$

Code blocks

Using markdown ```:

def foo():
  return 1

Using native notation:

 def foo():
   return 1
Raw
atom-unhacked.md

Atom unhacking

Goal:

Оvercome Atom limitations (too much hackability, slow startup, unclear workflow for some features), while transfering from Notepad++ (overloaded user interface) for productive text editing

Also looked at:

  • sublime (very fast and compact, but too nested menus, errors on package load)
  • neovim (long learning curve)
  • spacemacs (no win32 version)
  • light table (not too fast, stumbled at changing color theme)
  • brackets (html, no easy python running)
  • vscode (great for coding, but too heavy as text editor)

Features wanted:

  • fast uptime
  • portable (win32) version
  • no clutter in menus (as in Sublime) or interface (as in NPP)
  • editing with minimal distraction (as in Sublime)
  • run python easily (used to Spyder IDE)

Atom concepts:

  • packages
  • command line with [Ctrl]-[Shift]-[P]
  • themes
  • keymaps
  • atom-uri
  • panes: tutorial: vertical panes not explianed
  • selections:
    • why a dedicated menu for that?
    • is it all about [shift]-something?
    • what is Add Selection?

Complaints:

  • why you put so many default packages in Atom?
  • can there be a light version of Atom?
  • mixed levels for Packages menu
  • clettered File menu

Useful steps taken:

  • reduce uptime, less packages, see Packages - timecop output
  • install sublime-style-column-selection
  • markdown syntax highlighting (but which package is it?)
  • scripts package

My impossibles:

  • =========== header markdown highlighting
  • show Packages - timecop pane on startup
  • notepad F5 timestamp
  • approaches to prevew and select a style theme
  • autosave
  • git is stuck in win32 as in atom/github#986, even with LOCAL_GIT_DIRECTORY variable set
  • markdown snippets not available
  • text wrapping is ugly

To learn:

  • run python code, with ipython
  • telechat
  • how does apm work?

Tags (ideas):

Raw
msword_format.txt
> doc seems like a memory dump
On Windows:
- <http://code.activestate.com/recipes/279003-converting-word-documents-to-text/>
To read docx:
- <https://github.com/mikemaccana/python-docx>
- <https://pypi.python.org/pypi/docx2txt>
Generate docx from doc:
- Use [pyoo](https://pypi.python.org/pypi/pyoo) to connect to libreoffice to convert to docx
Linux-only:
- <http://vitus.wagner.pp.ru/software/catdoc/>
- <https://github.com/rembish/Miette>
- <https://github.com/rembish/Miette/blob/master/miette/doc.py>
- <https://textract.readthedocs.io/en/stable/>
- <http://www-stud.rbi.informatik.uni-frankfurt.de/~markus/antiword/>
- <http://wvware.sourceforge.net/>
Other:
- <https://wiki.openoffice.org/wiki/Odt2txt.py>
- <https://www.abisource.com/>
Raw
sphinx.md

Key commands

  • sphinx-quickstart creates folders for documentation

  • sphinx-apidoc -o src src/pkg creates file with directives in src folder

  • sphinx-build src dst -b htmlrequires conf.py and index.rst in src folder

sphinx-apidoc

Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_pattern,
...]

Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.

The <exclude_pattern>s can be file and/or directory patterns that will be
excluded from generation.

Note: By default this script will not overwrite already created files.

Options:
  -h, --help            show this help message and exit
  -o DESTDIR, --output-dir=DESTDIR
                        Directory to place all output
  -d MAXDEPTH, --maxdepth=MAXDEPTH
                        Maximum depth of submodules to show in the TOC
                        (default: 4)
  -f, --force           Overwrite existing files
  -l, --follow-links    Follow symbolic links. Powerful when combined with
                        collective.recipe.omelette.
  -n, --dry-run         Run the script without creating files
  -e, --separate        Put documentation for each module on its own page
  -P, --private         Include "_private" modules
  -T, --no-toc          Don't create a table of contents file
  -E, --no-headings     Don't create headings for the module/package packages
                        (e.g. when the docstrings already contain them)
  -M, --module-first    Put module documentation before submodule
                        documentation
  --implicit-namespaces
                        Interpret module paths according to PEP-0420 implicit
                        namespaces specification
  -s SUFFIX, --suffix=SUFFIX
                        file suffix (default: rst)
  -F, --full            Generate a full project with sphinx-quickstart
  -a, --append-syspath  Append module_path to sys.path, used when --full is
                        given
  -H HEADER, --doc-project=HEADER
                        Project name (default: root module name)
  -A AUTHOR, --doc-author=AUTHOR
                        Project author(s), used when --full is given
  -V VERSION, --doc-version=VERSION
                        Project version, used when --full is given
  -R RELEASE, --doc-release=RELEASE
                        Project release, used when --full is given, defaults
                        to --doc-version
  --version             Show version information and exit

  Extension options:
    --ext-autodoc       enable autodoc extension
    --ext-doctest       enable doctest extension
    --ext-intersphinx   enable intersphinx extension
    --ext-todo          enable todo extension
    --ext-coverage      enable coverage extension
    --ext-imgmath       enable imgmath extension
    --ext-mathjax       enable mathjax extension
    --ext-ifconfig      enable ifconfig extension
    --ext-viewcode      enable viewcode extension
    --ext-githubpages   enable githubpages extension

sphinx-build -h

Sphinx v1.6.3
Usage: sphinx-build [options] sourcedir outdir [filenames...]

Filename arguments:
  without -a and without filenames, write new and changed files.
  with -a, write all files.
  with filenames, write these.

Options:
  -h, --help          show this help message and exit
  --version           show version information and exit

  General options:
    -b BUILDER        builder to use; default is html
    -a                write all files; default is to only write new and
                      changed files
    -E                don't use a saved environment, always read all files
    -d PATH           path for the cached environment and doctree files
                      (default: outdir/.doctrees)
    -j N              build in parallel with N processes where possible

  Build configuration options:
    -c PATH           path where configuration file (conf.py) is located
                      (default: same as sourcedir)
    -C                use no config file at all, only -D options
    -D setting=value  override a setting in configuration file
    -A name=value     pass a value into HTML templates
    -t TAG            define tag: include "only" blocks with TAG
    -n                nit-picky mode, warn about all missing references

  Console output options:
    -v                increase verbosity (can be repeated)
    -q                no output on stdout, just warnings on stderr
    -Q                no output at all, not even warnings
    --color           Do emit colored output (default: auto-detect)
    -N, --no-color    Do not emit colored output (default: auot-detect)
    -w FILE           write warnings (and errors) to given file
    -W                turn warnings into errors
    -T                show full traceback on exception
    -P                run Pdb on exception

For more information, visit <http://sphinx-doc.org/>.
Raw
tables_with_breaks.py
# based on <https://stackoverflow.com/a/26937531/1758363>
from beautifultable import BeautifulTable
table = BeautifulTable()
table.column_headers = ["name", "rank", "gender"]
table.append_row(["Jacob\nSmith", 1, "boy"])
print(table)
"""
+-----------------+------+--------+
| name | rank | gender |
+-----------------+------+--------+
| Jacob
and Jones | 1 | boy |
+-----------------+------+--------+
"""
from texttable import Texttable
t = Texttable()
t.add_rows([['Name', 'Age'], ['Alice\nThe Menace', 24], ['Bob', 19]])
print (t.draw())
"""
+-------+-----+
| Name | Age |
+=======+=====+
| Alice | 24 |
| Bob | |
+-------+-----+
| Bob | 19 |
+-------+-----+
"""
from tabulate import tabulate
tbl = tabulate([['Alice\nThe Menace', 24],
['Bob', 19]],
headers=['Name', 'Age'],
tablefmt="grid")
print(tbl)
"""
+------------+-------+
| Name | Age |
+============+=======+
| Alice | 24 |
| The Menace | |
+------------+-------+
| Bob | 19 |
+------------+-------+
"""
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment