{ "info": { "author": "Robert Nowotny", "author_email": "rnowotny1966@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: Python", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "rst_include\n===========\n\n|Pypi Status| |pyversion| |license| |maintenance|\n\n|Build Status| |Codecov Status| |Better Code| |code climate| |snyk security|\n\n.. |license| image:: https://img.shields.io/github/license/webcomics/pywine.svg\n :target: http://en.wikipedia.org/wiki/MIT_License\n.. |maintenance| image:: https://img.shields.io/maintenance/yes/2019.svg\n.. |Build Status| image:: https://travis-ci.org/bitranox/rst_include.svg?branch=master\n :target: https://travis-ci.org/bitranox/rst_include\n.. for the pypi status link note the dashes, not the underscore !\n.. |Pypi Status| image:: https://badge.fury.io/py/rst-include.svg\n :target: https://badge.fury.io/py/rst_include\n.. |Codecov Status| image:: https://codecov.io/gh/bitranox/rst_include/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/bitranox/rst_include\n.. |Better Code| image:: https://bettercodehub.com/edge/badge/bitranox/rst_include?branch=master\n :target: https://bettercodehub.com/results/bitranox/rst_include\n.. |snyk security| image:: https://snyk.io/test/github/bitranox/rst_include/badge.svg\n :target: https://snyk.io/test/github/bitranox/rst_include\n.. |code climate| image:: https://api.codeclimate.com/v1/badges/ff3f414903627e5cfc35/maintainability\n :target: https://codeclimate.com/github/bitranox/rst_include/maintainability\n :alt: Maintainability\n.. |pyversion| image:: https://img.shields.io/badge/python-%3E%3D3.6-brightgreen.svg\n :target: https://badge.fury.io/py/rst_include\n :alt: Python Version\n\nsince You can not include files into RST files on github and PyPi, You can replace those imports with this software.\n\nThat means You can locally write Your RST documents (for instance with pycharm) and use there\nthe .. include: option to include other RST Files or code snippets into Your Document.\nAfterwards You can run this software to create a monolithic README.rst that can be viewed on Github or Pypi\n\nYou might also include Text/Code from Jupyter Notebooks (sorry, no pictures at the moment, but it is not very hard to do that)\n\nThis has many advantages like :\n\n- dont repeat Yourself, create standard blocks to include into Your documentation\n- include tested code snippets from Your code files into Your documentation, to avoid untested or outdated documentation\n- include other RST Files\n- very simple usage, throwing exit codes to detect errors on documentation at travis build-time\n- commandline or programmatic interface, You can even use it in the travis.yml\n- commandline interface supporting shellscript, cmd, pipes, config-files\n\nThis README was also created with rst_include, You might look at ./docs/README_template.rst ,\nbuild_docs.sh, build_docs.cmd and build_docs.py as examples. (they all do the same, just different versions)\n\nThe travis.yml builds the Documentation on every run, so You can be sure that there are no Errors.\nrst_include does only work on python > 3.6\n\n`100% code coverage `_, mypy static type checking, tested under `Linux, OsX, Windows and Wine `_, automatic daily builds and monitoring\n\n----\n\n- `Installation and Upgrade`_\n- `Basic Usage`_\n- Examples\n - `Example Build Script Python`_\n - `Example Build Script DOS Batch`_\n - `Example Build Script Shellscript`_\n - `RST Includes Examples`_\n - `simple code include`_\n - `text or RST file include`_\n - `include jupyter notebooks`_\n- `RST Include Parameters`_\n- `Requirements`_\n- `Acknowledgements`_\n- `Contribute`_\n- `Report Issues `_\n- `Pull Request `_\n- `Code of Conduct `_\n- `License`_\n- `Changelog`_\n\n-----------------------------------------------------------------\n\nInstallation and Upgrade\n------------------------\n\nFrom source code:\n\n.. code-block:: bash\n\n # normal install\n python setup.py install\n # test without installing\n python setup.py test\n\nvia pip latest Release:\n\n.. code-block:: bash\n\n # latest Release from pypi\n # under Linux You have to use sudo, or it will not be installed as a commandline application\n # [sudo] means, that the command \"sudo\" is optional for Linux if You want to use it from bash commandline\n [sudo] pip3 install rst_include\n\n # test without installing\n [sudo] pip3 install rst_include --install-option test\n\nvia pip latest Development Version:\n\n.. code-block:: bash\n\n # upgrade all dependencies regardless of version number (PREFERRED)\n [sudo] pip3 install --upgrade https://github.com/bitranox/rst_include/archive/master.zip --upgrade-strategy eager\n # normal install\n [sudo] pip3 install --upgrade https://github.com/bitranox/rst_include/archive/master.zip\n # test without installing\n [sudo] pip3 install https://github.com/bitranox/rst_include/archive/master.zip --install-option test\n\nvia requirements.txt:\n\n.. code-block:: bash\n\n # Insert following line in Your requirements.txt:\n # for the latest Release:\n rst_include\n # for the latest Development Version :\n https://github.com/bitranox/rst_include/archive/master.zip\n\n # to install and upgrade all modules mentioned in requirements.txt:\n [sudo] pip3 install --upgrade -r //requirements.txt\n\nvia python:\n\n.. code-block:: python\n\n # for the latest Release\n [sudo] python3 -m pip install upgrade rst_include\n\n # for the latest Development Version\n [sudo] python3 -m pip install upgrade https://github.com/bitranox/rst_include/archive/master.zip\n\n-----------------------------------------------------------------\n\nBasic Usage\n-----------\n\nsince rst_include is registered as a console script command with Your current python interpreter, You have to use the command \"rst_include\" (not \"rst_include.py\")\n\n\n- issue command :\n\n.. code-block:: shell\n\n # issue command on shell or windows commandline\n $> rst_include [OPTIONS]\n\n # or, if python/bin is not in Your python path :\n # on Windows\n $> c:\\python37\\scripts\\rst_include [OPTIONS]\n # on Linux/oSX\n $> /python37/bin/rst_include [OPTIONS]\n\n # issue command with python interpreter\n $> python -m rst_include [OPTIONS]\n\n\n\n- get help :\n\n.. code-block:: shell\n\n # get help on shell or windows commandline\n $> rst_include -h\n\n.. code-block:: shell\n\n usage: rst_include [-h] {include,replace} ...\n\n Process .rst File Includes\n\n positional arguments:\n {include,replace}\n include include rst includes\n replace string replace\n\n optional arguments:\n -h, --help show this help message and exit\n\n check the documentation on github\n\n.. code-block:: shell\n\n # get help on shell or windows commandline for include\n $> rst_include include -h\n\n.. code-block:: shell\n\n usage: rst_include include [-h] [-s [source]] [-t [target]]\n [-se [source encoding]] [-te [target encoding]]\n [-i] [-q] [-c [configfile.py]]\n\n optional arguments:\n -h, --help show this help message and exit\n -s [source], --source [source]\n default: stdin\n -t [target], --target [target]\n default: stdout\n -se [source encoding], --source_encoding [source encoding]\n default: utf-8-sig\n -te [target encoding], --target_encoding [target encoding]\n default: utf-8\n -i, --inplace inplace - target file = sourcefile\n -q, --quiet quiet\n -c [configfile.py], --config [configfile.py]\n If no filename is passed, the default conf_rst_inc.py\n is searched in the current directory\n\n.. code-block:: shell\n\n # get help on shell or windows commandline for string replace\n $> rst_include replace -h\n\n.. code-block:: shell\n\n usage: rst_include replace [-h] [-s [source]] [-t [target]]\n [-se [source encoding]] [-te [target encoding]]\n [-i] [-q]\n old new [count]\n\n positional arguments:\n old old\n new new\n count count\n\n optional arguments:\n -h, --help show this help message and exit\n -s [source], --source [source]\n default: stdin\n -t [target], --target [target]\n default: stdout\n -se [source encoding], --source_encoding [source encoding]\n default: utf-8-sig\n -te [target encoding], --target_encoding [target encoding]\n default: utf-8\n -i, --inplace inplace - target file = sourcefile\n -q, --quiet quiet\n\n- replace the include statements in source.rst and save it to target.rst via commandline parameters :\n\n.. code-block:: shell\n\n # replace the include statements on shell or windows commandline\n # path can be relative or absolute path\n # examples :\n\n # relativ path\n $> rst_include include -s ./source.rst -t ./target.rst\n\n # absolute path\n $> rst_include include -s /project/docs/source.rst -t /project/docs/target.rst\n\n # on linux via pipe\n $> cat /project/docs/source.rst | rst_include include > /project/docs/target.rst\n\n # on Windows via pipe\n $> type /project/docs/source.rst | rst_include include > /project/docs/target.rst\n\n\n- replace include statements on multiple files via config.py :\n\n.. code-block:: shell\n\n # replace the include statements on shell or windows commandline\n # path to the config file can be absolute or relative path\n # option -c or --config :\n\n # will try to load the default conf_rst_inc.py from the current directory\n $> rst_include include -c\n\n # will load another config file another directory\n $> rst_include include -c ./conf_this_project.py\n\nStructure of the configuration file:\n\nthe files are processed in the given order, by that way You can even realize nested .. include:: blocks.\n\nYou might also specify the encoding for source and target files\n\n.. code-block:: python\n\n from rst_include import *\n\n # set config here\n rst_conf = RstConf()\n\n # paths absolute, or relative to the location of the config file\n # the notation for relative files is like on windows or linux - not like in python.\n # so You might use ../../some/directory/some_document.rst to go two levels back.\n # avoid absolute paths since You never know where the program will run.\n rst_conf.l_rst_files = [RstFile(source='./rst_include/tests/test1_no_includes_template.rst',\n target='./rst_include/tests/test1_no_includes_result.rst',\n # default = utf-8-sig because it can read utf-8 and utf-8-sig\n source_encoding='utf-8-sig',\n # default = utf-8\n target_encoding='utf-8'\n ),\n RstFile(source='./rst_include/tests/test2_include_samedir_template.rst',\n target='./rst_include/tests/test2_include_samedir_result.rst'),\n RstFile(source='./rst_include/tests/test3_include_subdir_template.rst',\n target='./rst_include/tests/test3_include_subdir_result.rst'),\n RstFile(source='./rst_include/tests/test4_include_nocode_template.rst',\n target='./rst_include/tests/test4_include_nocode_result.rst')]\n\nAdditional You can easily replace (also multiline) text strings :\n\n.. code-block:: shell\n\n # replace text strings easily\n # examples :\n\n $> rst_include replace -s ./source.rst -t ./target.rst \"{template_string}\" \"new content\"\n\n # multiline example\n # note ${IFS} is the standard bash seperator\n $> rst_include replace --inplace -s ./source.txt \"line1${IFS}line2\" \"line1${IFS}something_between${IFS}line2\"\n\n\npiping under Linux:\n\n.. code-block:: shell\n\n # piping examples\n $> rst_include include -s ./source.rst | rst_include replace -t ./target.rst \"{template_string}\" \"new content\"\n # same result\n $> cat ./source.rst | rst_include include | rst_include replace \"{template_string}\" \"new content\" > ./target.rst\n\n # multiline example\n $> cat ./text.txt | rst_include replace \"line1${IFS}line2\" \"line1${IFS}something_between${IFS}line2\" > ./text.txt\n\n\n-----------------------------------------------------------------\n\nExample Build Script Python\n===========================\n\n.. code-block:: python\n\n import argparse\n import errno\n import logging\n import os\n import sys\n from rst_include import *\n from rst_include.libs import lib_log\n import subprocess\n\n\n # CONSTANTS & PROJECT SPECIFIC FUNCTIONS\n codeclimate_link_hash = \"ff3f414903627e5cfc35\"\n\n\n def project_specific(repository_slug, repository, repository_dashed):\n # PROJECT SPECIFIC\n logger = logging.getLogger('project_specific')\n logger.info('create help documentation files {dir}'.format(dir=os.path.abspath(os.path.curdir)))\n subprocess.run('{sys_executable} ./rst_include/rst_include.py -h > ./docs/rst_include_help_output.txt'.format(sys_executable=sys.executable), shell=True, check=True)\n subprocess.run('{sys_executable} ./rst_include/rst_include.py include -h > ./docs/rst_include_help_include_output.txt'.format(sys_executable=sys.executable), shell=True, check=True)\n subprocess.run('{sys_executable} ./rst_include/rst_include.py replace -h > ./docs/rst_include_help_replace_output.txt'.format(sys_executable=sys.executable), shell=True, check=True)\n\n\n def parse_args(cmd_args=sys.argv[1:]):\n # type: ([]) -> []\n parser = argparse.ArgumentParser(\n description='Create Readme.rst',\n epilog='check the documentation on github',\n add_help=True)\n\n parser.add_argument('travis_repo_slug', metavar='TRAVIS_REPO_SLUG in the form \"/\"')\n args = parser.parse_args(cmd_args)\n return args, parser\n\n\n def main(args):\n logger = logging.getLogger('build_docs')\n logger.info('create the README.rst')\n travis_repo_slug = args.travis_repo_slug\n repository = travis_repo_slug.split('/')[1]\n repository_dashed = repository.replace('_', '-')\n\n project_specific(travis_repo_slug, repository, repository_dashed)\n\n \"\"\"\n paths absolute, or relative to the location of the config file\n the notation for relative files is like on windows or linux - not like in python.\n so You might use ../../some/directory/some_document.rst to go two levels back.\n avoid absolute paths since You never know where the program will run.\n \"\"\"\n\n logger.info('include the include blocks')\n rst_inc(source='./docs/README_template.rst',\n target='./README.rst')\n\n # please note that the replace syntax is not shown correctly in the README.rst,\n # because it gets replaced itself by the build_docs.py\n # we could overcome this by first replacing, and afterwards including -\n # check out the build_docs.py for the correct syntax !\n logger.info('replace repository related strings')\n rst_str_replace(source='./README.rst',\n target='',\n old='bitranox/rst_include',\n new=travis_repo_slug,\n inplace=True)\n rst_str_replace(source='./README.rst',\n target='',\n old='rst_include',\n new=repository,\n inplace=True)\n rst_str_replace(source='./README.rst',\n target='',\n old='rst-include',\n new=repository_dashed,\n inplace=True)\n\n rst_str_replace(source='./README.rst',\n target='',\n old='ff3f414903627e5cfc35',\n new=codeclimate_link_hash,\n inplace=True)\n\n logger.info('done')\n sys.exit(0)\n\n\n if __name__ == '__main__':\n lib_log.setup_logger()\n main_logger = logging.getLogger('main')\n try:\n _args, _parser = parse_args()\n\n main(_args)\n except FileNotFoundError:\n # see https://www.thegeekstuff.com/2010/10/linux-error-codes for error codes\n sys.exit(errno.ENOENT) # No such file or directory\n except FileExistsError:\n sys.exit(errno.EEXIST) # File exists\n except TypeError:\n sys.exit(errno.EINVAL) # Invalid Argument\n except ValueError:\n sys.exit(errno.EINVAL) # Invalid Argument\n\nExample Build Script DOS Batch\n==============================\n\n.. code-block:: bat\n\n REM\n REM rst_include needs to be installed and python paths set correctly\n @echo off\n cls\n\n REM # You might also use Environment Variable here, or as commandline parameter\n REM # this is just an example, I use actually the build_readme.py python file myself\n REM # I do not recommend cmd files anymore - why it it is so much easier under python ...\n REM # I am sure there is a more elegant was to do it on batch files, this is only an example\n\n SET repository_slug=\"bitranox/rst_include\"\n SET repository=\"rst_include\"\n SET codeclimate_link_hash=\"ff3f414903627e5cfc35\"\n\n REM # get dashed repository name for pypi links\n echo %repository% | rst_include replace \"_\" \"-\" > temp.txt\n set /p repository_dashed= < temp.txt\n del temp.txt\n\n\n REM paths absolute, or relative to the location of the config file\n REM the notation for relative files is like on windows or linux - not like in python.\n REM so You might use ../../some/directory/some_document.rst to go two levels back.\n REM avoid absolute paths since You never know where the program will run.\n\n echo 'create the sample help outputs'\n rst_include -h > ./docs/rst_include_help_output.txt\n rst_include include -h > ./docs/rst_include_help_include_output.txt\n rst_include replace -h > ./docs/rst_include_help_replace_output.txt\n\n echo \"import the include blocks\"\n rst_include include -s ./docs/README_template.rst -t ./README.rst\n\n REM please note that the replace syntax is not shown correctly in the README.rst,\n REM because it gets replaced itself by the build_docs.py\n REM we could overcome this by first replacing, and afterwards including -\n REM check out the build_docs.cmd for the correct syntax !\n\n echo \"replace repository_slug\"\n rst_include --inplace replace -s ./docs/README_template.rst bitranox/rst_include %repository_slug%\n echo \"replace repository\"\n rst_include --inplace replace -s ./docs/README_template.rst rst_include %repository%\n echo \"replace repository_dashed\"\n rst_include --inplace replace -s ./docs/README_template.rst rst-include %repository_dashed%\n echo \"replace codeclimate_link_hash\"\n rst_include --inplace replace -s ./docs/README_template.rst ff3f414903627e5cfc35 %codeclimate_link_hash%\n\n echo 'finished'\n\nExample Build Script Shellscript\n================================\n\n.. code-block:: shell\n\n #!/bin/bash\n\n ### CONSTANTS\n codeclimate_link_hash=\"ff3f414903627e5cfc35\"\n # TRAVIS_TAG\n\n function include_dependencies {\n local my_dir=\"$( cd \"$(dirname \"${BASH_SOURCE[0]}\")\" ; pwd -P )\" # this gives the full path, even for sourced scripts\n chmod +x \"${my_dir}\"/lib_bash/*.sh\n source \"${my_dir}/lib_bash/lib_color.sh\"\n }\n\n include_dependencies # we need to do that via a function to have local scope of my_dir\n\n function check_repository_name {\n if [[ -z ${TRAVIS_REPO_SLUG} ]]\n then\n clr_bold clr_red \"ERROR no travis repository name set - exiting\"\n exit 1\n fi\n }\n\n clr_bold clr_green \"Build README.rst for repository: ${TRAVIS_REPO_SLUG}\"\n\n check_repository_name\n\n repository=\"${TRAVIS_REPO_SLUG#*/}\" # \"username/repository_name\" --> \"repository_name\"\n repository_dashed=\"$( echo -e \"$repository\" | tr '_' '-' )\" # \"repository_name --> repository-name\"\n\n clr_green \"create the sample help outputs\"\n rst_include -h > ./docs/rst_include_help_output.txt\n rst_include include -h > ./docs/rst_include_help_include_output.txt\n rst_include replace -h > ./docs/rst_include_help_replace_output.txt\n\n clr_green \"import the include blocks\"\n rst_include include -s ./docs/README_template.rst -t ./docs/README_template_included.rst\n\n clr_green \"replace repository strings\"\n\n # please note that the replace syntax is not shown correctly in the README.rst,\n # because it gets replaced itself by the build_docs.py\n # we could overcome this by first replacing, and afterwards including -\n # check out the build_docs.sh for the correct syntax !\n\n # example for piping\n cat ./docs/README_template_included.rst \\\n | rst_include replace \"bitranox/rst_include\" \"${TRAVIS_REPO_SLUG}\" \\\n | rst_include replace \"rst_include\" \"$rst_include\" \\\n | rst_include replace \"rst-include\" \"$rst-include\" \\\n | rst_include replace \"ff3f414903627e5cfc35\" \"$ff3f414903627e5cfc35\" \\\n > ./README.rst\n\n clr_green \"cleanup\"\n rm ./docs/README_template_included.rst\n\n clr_green \"done\"\n clr_green \"******************************************************************************************************************\"\n clr_bold clr_green \"FINISHED building README.rst\"\n clr_green \"******************************************************************************************************************\"\n\n-----------------------------------------------------------------\n\nRST Includes Examples\n=====================\n\nsimple code include\n===================\n\n.. code-block:: bash\n\n # simple text include, empty line after\n .. include:: ./include1.py\n :code: python\n :number-lines: 10\n :start-line: 6\n :end-line: 23\n :start-after: # start marker\n :end-before: # end-marker\n :encoding: utf-8\n\n\ntext or RST file include\n========================\n.. code-block:: bash\n\n # simple text include, without code setting - it is imported as normal textfile, as it is.\n # You might also include other rst files\n .. include:: include3.py\n :start-line: 0 # working, also end-line, etc ... all others suppressed.\n :number-lines: # not working without :code: setting\n\ninclude jupyter notebooks\n=========================\n\njupyter notebooks can be first converted to rst via nbconvert, see : https://nbconvert.readthedocs.io/en/latest/usage.html#convert-rst\n\npandoc is a requirement for nbconvert, see : https://pandoc.org/\n\n\n.. code-block:: bash\n\n # convert the attached test.ipynb to test.rst\n $ jupyter nbconvert --to rst test.ipynb\n\nunfortunately the pictures are not shown and needed to be extracted - a first hint might be : https://gist.github.com/sglyon/5687b8455a0107afc6f4c60b5f313670\n\nI would prefer to exctract the pictures after the conversion to RST, and make it a module in rst_include.\nFilenames can be a hash of the picture data, in order to avoid web caching issues.\n\n-----------------------------------------------------------------\n\nRST Include Parameters\n======================\n\ntaken from : http://docutils.sourceforge.net/docs/ref/rst/directives.html\n\nStandard data files intended for inclusion in reStructuredText documents are distributed with the Docutils source code, located in the \"docutils\" package in the docutils/parsers/rst/include directory.\nTo access these files, use the special syntax for standard \"include\" data files, angle brackets around the file name:\n\n\n.. code-block:: bash\n\n .. include:: # not supported now\n\n\nThe current set of standard \"include\" data files consists of sets of substitution definitions. See reStructuredText Standard Definition Files for details.\n\nThe following options are recognized:\n\n.. code-block:: bash\n\n # Only the content starting from this line will be included.\n # (As usual in Python, the first line has index 0 and negative values count from the end.)\n # Combining start/end-line and start-after/end-before is possible.\n # The text markers will be searched in the specified lines (further limiting the included content).\n start-line : integer\n\n.. code-block:: bash\n\n # Only the content up to (but excluding) this line will be included.\n # Combining start/end-line and start-after/end-before is possible.\n # The text markers will be searched in the specified lines (further limiting the included content).\n end-line : integer\n\n.. code-block:: bash\n\n # Only the content after the first occurrence of the specified text will be included.\n # Combining start/end-line and start-after/end-before is possible.\n # The text markers will be searched in the specified lines (further limiting the included content).\n start-after : text to find in the external data file\n\n.. code-block:: bash\n\n # Only the content before the first occurrence of the specified text (but after any after text) will be included.\n # Combining start/end-line and start-after/end-before is possible.\n # The text markers will be searched in the specified lines (further limiting the included content).\n end-before : text to find in the external data file\n\n.. code-block:: bash\n\n # The entire included text is inserted into the document as a single literal block.\n literal : flag (empty)\n\n.. code-block:: bash\n\n # The argument and the content of the included file are passed to the code directive (useful for program listings).\n # (New in Docutils 0.9)\n code : formal language (optional)\n\n.. code-block:: bash\n\n # Precede every code line with a line number. The optional argument is the number of the first line (default 1).\n # Works only with code or literal. (New in Docutils 0.9)\n number-lines : [start line number]\n\n.. code-block:: bash\n\n # The text encoding of the external data file. Defaults to the document's input_encoding.\n encoding : name of text encoding\n\n.. code-block:: bash\n\n # Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs.\n # Defaults to the tab_width configuration setting.\n tab-width : integer\n\n.. code-block:: bash\n\n With code or literal the common options :class: and :name: are recognized as well.\n all other option in the format :