Metadata-Version: 1.2
Name: snippy
Version: 0.8.0
Summary: Command, solution, reference and code snippet manager.
Home-page: https://github.com/heilaaks/snippy
Author: Heikki J. Laaksonen
Author-email: laaksonen.heikki.j@gmail.com
License: GNU Affero General Public License v3 or later
Description-Content-Type: text/x-rst
Description: |badge-pypiv| |badge-pys| |badge-pyv| |badge-cov| |badge-docs| |badge-build|
        
        Features
        ========
        
        Manage command snippets, solution examples and reference links from console
        or REST API server. The tool is designed to support software development and
        troubleshooting workflows by collecting command examples, troubleshooting
        solutions and links into one content manager. The tool may be helpful for
        example when working with different open source components that all have
        different configuration settings and troubleshooting methods. You can share
        the best examples through common data serialization languages YAML or JSON
        or from a REST API server.
        
        Content is divided into three categories called snippets, solutions and
        references. Snippets are short command examples. Solutions are longer
        solution descriptions and references are links to important web pages and
        resources. You can combine metadata like tags, group or links with the
        content in order to help searching and tracking stored content.
        
        You can operate all content directly from command line with six operations:
        create, search, update, delete, import and export. These operations manage
        the content in persistent file storage installed into the same location as
        the tool.
        
        You can operate all content from `RESTish JSON API`_. server. The API follows
        a subset of the `JSON API V1.0`_ specification. The tool must be installed
        from Docker Hub or from the github repository if server functionality is
        required. The server functionality is not currently available when installed
        directly from PyPI.
        
        .. image:: https://asciinema.org/a/MEpDOPZLqDMySq7hwXGhCOliV.png
            :target: https://asciinema.org/a/MEpDOPZLqDMySq7hwXGhCOliV
            :alt: Snippy in action!
        
        Installation
        ============
        
        To install, run:
        
        .. code:: text
        
            pip install snippy --user
        
        To remove, run:
        
        .. code:: text
        
            pip uninstall --yes snippy
        
        To install from Docker Hub, run:
        
        .. code:: text
        
            docker pull heilaaks/snippy
        
        To install from Github, run:
        
        .. code-block:: text
        
            git clone https://github.com/heilaaks/snippy.git
            cd snippy
            make install
        
        Usage
        =====
        
        Snippy command line commands always include content operation and category.
        The content operation is one of the six basic operations and the category is
        either snippet, solution or reference. The content category is snippet by
        default. Metadata attached to the content allows adding brief description of
        the content, single group to which the content belongs, list of tags to
        assist search operations and a list of links for more information about the
        content.
        
        Snippy tool outputs always OK after successful operation and NOK with a failure
        string in case of failure. You can use debug option with the command to
        investigate possible problems. For more detailed troubleshooting instructions,
        please refer to the `contributing instructions`_.
        
        The workflow section below contains the basic use cases for command line
        interface. You can read more detailed documentation from the documentation
        hosted by the `Read the Docs`_.
        
        .. note::
        
           The tool is used by the author in Linux environment. There is an edit
           functionality with editor that always assumes vi editor. This limitation
           can be circumvented by using text based templates to import content or
           command line options in case of snippets.
        
        .. note::
        
           The default content is provided "as is" basis without warranties of any
           kind.
        
        Workflows
        =========
        
        Printing help and examples
        --------------------------
        
        Use help option with keyword examples to read about basic usage.
        
        .. code-block:: text
        
           snippy --help
           snippy --help examples
        
        Importing default content
        -------------------------
        
        Snippy instals by default without content. Following examples allow importing
        default content for snippets and solutions.
        
        .. code-block:: text
        
           snippy import --snippets --defaults
           snippy import --solutions --defaults
        
        Using docker container
        ----------------------
        
        Snippy tool is available also from Docker container. In this case the default
        content is already imported. How ever, the content cannot be changed because
        the container is immuateble and the content is not mapped from any volume from
        the host machine. Exactly same commands work with container version than the
        command line version.
        
        .. code-block:: text
        
           docker run heilaaks/snippy --help
           docker run heilaaks/snippy search --sall docker
        
        Searching content
        -----------------
        
        Printing all content to console
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        It is possible to print all snippets and solutions to console by using a dot
        in the search query. The only special character passed to the query is dot
        which matches to to any character.
        
        .. code-block:: text
        
           snippy search --sall .
           snippy search --solutions --sall .
        
        Filtering with grep
        ~~~~~~~~~~~~~~~~~~~
        
        With Linux grep it is possible to filter for example only the actual commands
        from the search query.
        
        .. code-block:: text
        
           snippy search --sall . --no-ansi | grep '\$'
           snippy search --sgrp docker --no-ansi | grep '\$'
        
        Filtering out solution content to list only the metadata.
        
        .. code-block:: text
        
           snippy search --solutions --sall . | grep -Ev '[^\s]+:'
        
        Creating content
        ----------------
        
        Create snippet with vi editor
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Following command uses vi editor to create new content. The command opens an
        input template where you can define the mandatory snippet and optional brief
        description, group, tags and links related to the snippet.
        
        .. code-block:: text
        
           snippy create --snippets --editor
        
        Create snippet from text template
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Following commands allows using a text template to import new snippet.
        
        .. code-block:: text
        
           snippy export --snippets --template
           snippy import --snippets -f snippet-template.txt
        
        Create solution from text template
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Following commands allows using a text template to import new solution.
        
        .. code-block:: text
        
           snippy export --solutions --template
           snippy import --snippets -f solution-template.txt
        
        Updating content
        ----------------
        
        Update snippet with vi editor
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Following command allows updating existing snippet with vi editor. The command
        will launch a vi editor which allows you to modify the content. The content is
        updated automatically after the file is saved and editor is exit.
        
        .. code-block:: text
        
           snippy update --digest 54e41e9b52a02b63
        
        Update solution from text template
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Following commands allow updating existing solution by exporting the content
        to text file and importing it again.
        
        .. code-block:: text
        
           snippy export --digest 76a1a02951f6bcb4
           snippy import --digest 76a1a02951f6bcb4 --file howto-debug-elastic-beats.txt
        
        Migrating content
        -----------------
        
        Exporting content
        ~~~~~~~~~~~~~~~~~
        
        Following commands allow exporting all snippets and solutions to YAML file that
        you use to back-up your data. The commands below will create snippets.yaml and
        solutions.yaml files into same directory where the command was executed. You can
        define the file name and path with the ``-f|--file`` option.
        
        .. code-block:: text
        
           snippy export --snippets
           snippy export --snippets -f my-snippets.yaml
           snippy export --solutions
           snippy export --solutions -f my-solutions.yaml
        
        Importing content
        ~~~~~~~~~~~~~~~~~
        
        Following commands allow importing snippets and solutions from default YAML files
        named snippets.yaml and solutions.yaml that must be located in the same directory
        where the command is executed. You can define the file name and path with the
        ``-f|--file`` option.
        
        .. code-block:: text
        
           snippy import --snippets
           snippy import --solutions
        
        Server
        ======
        
        The JSON REST API server is available when the tool is installed from Docker
        Hub or directly from the source code. The API is experimental and changes can
        be expected. The API is documented in Swagger Hub `OpenAPI definitions`_.
        
        .. code-block:: text
        
           sudo docker run -d --net="host" --name snippy heilaaks/snippy --server --log-json -vv
           curl -s -X GET "http://127.0.0.1:8080/snippy/api/app/v1/snippets?limit=2" -H "accept: application/vnd.api+json"
           curl -X GET "http://127.0.0.1:8080/snippy/api/app/v1/snippets?sall=docker&limit=2" -H "accept: application/vnd.api+json"
        
        You can change the port and IP address by defining them from the command
        line. Remember to remove the stopped container before starting it with new
        perameters.
        
        .. code-block:: text
        
           docker rm -f snippy
           sudo docker run -d --net="host" --name snippy heilaaks/snippy --server --port 8080 --ip 127.0.0.1 --log-json -vv
           curl -s -X GET "http://127.0.0.1:8080/snippy/api/app/v1/snippets?sall=docker&limit=2" -H "accept: application/vnd.api+json"
        
        You can see the logs from the server from the default Docker log. If you do
        not want to read JSON logs, remove the ``--log-json`` parameter from the
        server startup optons. You can remove all the logs by removing the ``-vv``
        option.
        
        .. code-block:: text
        
           docker rm -f snippy
           sudo docker run -d --net="host" --name snippy heilaaks/snippy --server --port 8080 --ip 127.0.0.1 -vv
           docker logs snippy
        
        You can remove the server with command example.
        
        .. code-block:: text
        
           docker rm -f snippy
        
        Note that Docker container is immutable and it does not share volume from the
        host. If you want to run a server that allows content modification, you must
        install the server from code repository.
        
        .. code-block:: text
        
           git clone https://github.com/heilaaks/snippy.git
           cd snippy
           make server
        
        With a local server, you can change to location of the storage from the
        default. If the default content is needed, you need to import it into the new
        location before starting the server.
        
        .. code-block:: text
        
           snippy import --defaults --storage-path ${HOME}/devel/temp
           snippy import --defaults --solutions --storage-path ${HOME}/devel/temp
           snippy --server --storage-path ${HOME}/devel/temp --port 8080 --ip 127.0.0.1 -vv
        
        Contributing
        ============
        
        Bug reports and feature Requests
        --------------------------------
        
        Run the failing command with ``--debug`` option to get a better idea what is failing. Please
        fill a bug report based on contributing_ instructions.
        
        
        .. |badge-pypiv| image:: https://img.shields.io/pypi/v/snippy.svg
           :target: https://pypi.python.org/pypi/snippy
        
        .. |badge-pys| image:: https://img.shields.io/pypi/status/snippy.svg
           :target: https://pypi.python.org/pypi/snippy
        
        .. |badge-pyv| image:: https://img.shields.io/pypi/pyversions/snippy.svg
           :target: https://pypi.python.org/pypi/snippy
        
        .. |badge-cov| image:: https://codecov.io/gh/heilaaks/snippy/branch/master/graph/badge.svg
           :target: https://codecov.io/gh/heilaaks/snippy
        
        .. |badge-docs| image:: https://readthedocs.org/projects/snippy/badge/?version=latest
           :target: http://snippy.readthedocs.io/en/latest/?badge=latest
        
        .. |badge-build| image:: https://travis-ci.org/heilaaks/snippy.svg?branch=master
           :target: https://travis-ci.org/heilaaks/snippy
        
        .. _Read the Docs: http://snippy.readthedocs.io/en/latest/
        
        .. _contributing instructions: https://github.com/heilaaks/snippy/blob/master/CONTRIBUTING.rst
        
        .. _RESTish JSON API: https://app.swaggerhub.com/apis/heilaaks/snippy/1.0
        
        .. _OpenAPI definitions: `RESTish JSON API`_
        
        .. _JSON API V1.0: http://jsonapi.org/format/
Keywords: command solution snippet reference link snippet manager server console
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
