From 3ec9681eb0dddd0272eae2d934ff038a48235cac Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Fri, 23 Dec 2016 00:45:39 +0800 Subject: [PATCH 1/6] Move docs to Sphinx --- .gitignore | 1 + README.rst | 375 ++----------------------------------- docs/Makefile | 20 ++ docs/conf.py | 176 +++++++++++++++++ docs/contributor-guide.rst | 236 +++++++++++++++++++++++ docs/index.rst | 68 +++++++ docs/make.bat | 36 ++++ docs/user-guide.rst | 321 +++++++++++++++++++++++++++++++ 8 files changed, 871 insertions(+), 362 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/contributor-guide.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/user-guide.rst diff --git a/.gitignore b/.gitignore index a2eec41..86f963f 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,6 @@ .DS_Store .python-version .tox +_build build dist diff --git a/README.rst b/README.rst index a1c32f4..bc40531 100644 --- a/README.rst +++ b/README.rst @@ -1,367 +1,20 @@ HTTP Prompt =========== -|Gitter| |PyPI| |Travis| |Appveyor| |Coverage| +|PyPI| |Travis| |Appveyor| |Coverage| |Gitter| HTTP Prompt is an interactive command-line HTTP client featuring autocomplete and syntax highlighting, built on HTTPie_ and prompt_toolkit_. -.. image:: https://raw.githubusercontent.com/eliangcs/http-prompt/master/http-prompt.gif +|Asciinema| +For find out more, please visit the following links: -Installation ------------- +* Home: https://http-prompt.com +* Documentation: https://docs.http-prompt.com +* GitHub: https://github.com/eliangcs/http-prompt +* Gitter: https://gitter.im/http-prompt/http-prompt -Just install it like a regular Python package:: - - $ pip install http-prompt - -You'll probably see some permission errors if you're trying to install it on -the system-wide Python. It isn't recommended. But if that's what you want to -do, you need to ``sudo``:: - - $ sudo pip install http-prompt - -Another alternative is to use ``--user`` option to install the package into -your user directory:: - - $ pip install --user http-prompt - -To upgrade HTTP Prompt, do:: - - $ pip install -U http-prompt - - -Quickstart ----------- - -To start a session, you use the ``http-prompt`` executable: - -.. code-block:: bash - - # Start with the last session or http://localhost:8000 - $ http-prompt - - # Start with the given URL - $ http-prompt http://httpbin.org - - # Start with some initial options - $ http-prompt localhost:8000/api --auth user:pass username=somebody - -Once you're in a session, you can use the following commands. - -To change URL address, use ``cd``: - -.. code-block:: bash - - # Relative URL path - > cd api/v1 - - # Absolute URL - > cd http://localhost/api - -To add headers, querystring, or body parameters, use the syntax as in HTTPie_. -The following are all valid: - -.. code-block:: bash - - > Content-Type:application/json username=john - > 'name=John Doe' apikey==abc - > Authorization:"Bearer auth_token" - -You can also add HTTPie_ options like this: - -.. code-block:: bash - - > --form --auth user:pass - > --verify=no username=jane - -To preview how HTTP Prompt is going to call HTTPie_, do: - -.. code-block:: bash - - > httpie post - http --auth user:pass --form POST http://localhost/api apikey==abc username=john - -You can temporarily override the request parameters by supplying options and -parameters in ``httpie`` command. The overrides won't affect the later -requests. - -.. code-block:: bash - - # No parameters initially - > httpie - http http://localhost - - # Override parameters temporarily - > httpie /api/something page==2 --json - http --json http://localhost/api/something page==2 - - # Current state is not affected by the above overrides - > httpie - http http://localhost - -Since v0.6.0, apart from ``httpie`` command, you can also use ``env`` to print -the current session: - -.. code-block:: bash - - > env - --verify=no - cd http://localhost - page==10 - limit==20 - -To actually send an HTTP request, enter one of the HTTP methods: - -.. code-block:: bash - - > get - > post - > put - > patch - > delete - > head - > options (*new in v0.8.0*) - -The above HTTP methods also support temporary overriding: - -.. code-block:: bash - - # No parameters initially - > httpie - http http://localhost - - # Send a request with some overrided parameters - > post /api/v1 --form name=jane - - # Current state remains intact - > httpie - http http://localhost - -To remove an existing header, a querystring parameter, a body parameter, or an -HTTPie_ option: - -.. code-block:: bash - - > rm -h Content-Type - > rm -q apikey - > rm -b username - > rm -o --auth - -To reset the session, i.e., clear all parameters and options: - -.. code-block:: bash - - > rm * - -To exit a session, simply enter: - -.. code-block:: bash - - > exit - - -Output Redirection ------------------- - -*New in v0.6.0.* - -You can redirect the output of a command to a file by using the syntax: - -.. code-block:: bash - - # Write output to a file - > COMMAND > /path/to/file - - # Append output to a file - > COMMAND >> /path/to/file - -where ``COMMAND`` can be one of the following: - -* ``env`` -* ``httpie`` -* HTTP actions: ``get``, ``post``, ``put``, ``patch``, ``delete``, ``head`` - - -Saving and Loading Sessions -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One of the use cases of output redirection is to save and load sessions, which -is especially useful for team collaboration, where you want to share your -sessions with your team members. - -To save your current session, you redirect the output of ``env`` to a file: - -.. code-block:: bash - - > env > /path/to/file - -To load a saved session, you can use ``source`` or ``exec``. Their only -difference is that ``exec`` wipes out the current session before loading. -Usage: - -.. code-block:: bash - - # Update the current session - > source /path/to/file - - # Overwrite the current session completely - > exec /path/to/file - - -Saving HTTP Respones -~~~~~~~~~~~~~~~~~~~~ - -Printing HTTP responses to the console is good for small text responses. For -larger text or binary data, you may want to save the response to a file. Usage: - -.. code-block:: bash - - # Save http://httpbin.org/image/png to a file - > cd http://httpbin.org/image/png - > get > pig.png - - # Or use this one-liner - > get http://httpbin.org/image/png > pig.png - - -Pipeline --------- - -*New in v0.7.0.* - -HTTP Prompt supports simplified pipeline syntax, where you can pipe the output -to a shell command: - -.. code-block:: bash - - # Replace 'localhost' to '127.0.0.1' - > httpie POST http://localhost | sed 's/localhost/127.0.0.1/' - http http://127.0.0.1 - - # Only print the line that contains 'User-Agent' using grep - > get http://httpbin.org/get | grep 'User-Agent' - "User-Agent": "HTTPie/0.9.6" - -On macOS, you can even copy the result to the clipboard using ``pbcopy``: - -.. code-block:: bash - - # Copy the HTTPie command to the clipboard (macOS only) - > httpie | pbcopy - -Another cool trick is to use jq_ to parse JSON data: - -.. code-block:: bash - - > get http://httpbin.org/get | jq '.headers."User-Agent"' - "HTTPie/0.9.6" - -**Note**: Syntax with multiple pipes is not supported currently. - - -Shell Substitution ------------------- - -*New in v0.7.0.* - -Shell substitution happens when you put a shell command between two backticks -like ``\`...\```. This syntax allows you compute a value from the shell -environment and assign the value to a parameter:: - - # Set date to current time - > date==`date -u +"%Y-%m-%d %H:%M:%S"` - > httpie - http http://localhost:8000 'date==2016-10-08 09:45:00' - - # Get password from a file. Suppose the file has a content of - # "secret_api_key". - > password==`cat ./apikey.txt` - > httpie - http http://localhost:8000 apikey==secret_api_key - - -Configuration -------------- - -*New in v0.4.0.* - -When launched for the first time, HTTP Prompt creates a user config file at -``$XDG_CONFIG_HOME/http-prompt/config.py`` (or ``%LOCALAPPDATA%/http-prompt/config.py`` -on Windows). By default, it's ``~/.config/http-prompt/config.py`` (or -``~/AppData/Local/http-prompt/config.py``). - -``config.py`` is a Python module with all the available options you can -customize. Don't worry. You don't need to know Python to edit it. Just open it -up with a text editor and follow the guidance inside. - - -Persistent Context ------------------- - -*New in v0.4.0.* - -HTTP Prompt keeps a data structure called *context* to represent your current -session. Every time you enter a command modifying your context, HTTP Prompt -saves the context to your filesystem, enabling you to resume your previous -session when you restart ``http-prompt``. - -The last saved context is located at ``$XDG_DATA_HOME/http-prompt/context.hp`` -(or ``%LOCALAPPDATA%/http-prompt/context.hp`` on Windows). By default, it's -``~/.local/share/http-prompt/context.hp`` (or ``~/AppData/Local/http-prompt/context.hp``). - -As context data may contain sensitive data like API keys, you should keep the -user data directory private. By default, HTTP Prompt sets the modes of -``$XDG_DATA_HOME/http-prompt`` to ``rwx------`` (i.e., ``700``) so that the -only person who can read it is the owner (you). - -**Note for users of older versions**: Since 0.6.0, HTTP Prompt only stores the -last context instead of grouping multiple contexts by hostnames and ports like -it did previously. We changed the behavior because the feature can be simply -replaced by ``env``, ``exec`` and ``source`` commands. See the discussion in -`issue #70 `_ for detail. - - -Roadmap -------- - -* Support for advanced HTTPie syntax, e.g, ``field:=json`` and ``field=@file.json`` -* Support for cURL command and raw format preview -* Improve autocomplete -* Python syntax evaluation -* HTTP/2 support - - -User Support ------------- - -We'd love to hear more from our users! Please use the following channels for -bug reports, feature requests, and questions: - -* `GitHub issues`_ -* `Gitter chat room`_ - - -Contributing ------------- - -Are you a developer and interested in contributing to HTTP Prompt? See -CONTRIBUTING.rst_. - - -Thanks ------- - -* HTTPie_: for designing such a user-friendly HTTP CLI -* prompt_toolkit_: for simplifying the work of building an interactive CLI -* Parsimonious_: for the PEG parser used by this project -* pgcli_: for the inspiration of this project -* Contributors_: for improving this project - - -.. |Gitter| image:: https://badges.gitter.im/http-prompt/http-prompt.svg - :target: https://gitter.im/http-prompt/http-prompt .. |PyPI| image:: https://img.shields.io/pypi/v/http-prompt.svg :target: https://pypi.python.org/pypi/http-prompt @@ -375,13 +28,11 @@ Thanks .. |Coverage| image:: https://coveralls.io/repos/github/eliangcs/http-prompt/badge.svg?branch=master :target: https://coveralls.io/github/eliangcs/http-prompt?branch=master +.. |Gitter| image:: https://badges.gitter.im/http-prompt/http-prompt.svg + :target: https://gitter.im/http-prompt/http-prompt + +.. |Asciinema| image:: https://asciinema.org/a/96613.png + :target: https://asciinema.org/a/96613?theme=monokai&size=medium&autoplay=1 -.. _CONTRIBUTING.rst: https://github.com/eliangcs/http-prompt/blob/master/CONTRIBUTING.rst -.. _Contributors: https://github.com/eliangcs/http-prompt/graphs/contributors -.. _GitHub issues: https://github.com/eliangcs/http-prompt/issues -.. _Gitter chat room: https://gitter.im/http-prompt/http-prompt -.. _HTTPie: https://github.com/jkbrzt/httpie -.. _jq: https://stedolan.github.io/jq/ -.. _Parsimonious: https://github.com/erikrose/parsimonious -.. _pgcli: https://github.com/dbcli/pgcli +.. _HTTPie: https://httpie.org .. _prompt_toolkit: https://github.com/jonathanslenders/python-prompt-toolkit diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..8d31556 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = HTTPPrompt +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b379055 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,176 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# HTTP Prompt documentation build configuration file, created by +# sphinx-quickstart on Wed Dec 21 20:28:44 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +from collections import OrderedDict + +from http_prompt import __version__ + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'HTTP Prompt' +copyright = '2016, Chang-Hung Liang' +author = 'Chang-Hung Liang' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = __version__ +# The full version, including alpha/beta/rc tags. +release = __version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'HTTPPromptdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'HTTPPrompt.tex', 'HTTP Prompt Documentation', + 'Chang-Hung Liang', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'httpprompt', 'HTTP Prompt Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'HTTPPrompt', 'HTTP Prompt Documentation', + author, 'HTTPPrompt', 'One line description of project.', + 'Miscellaneous'), +] + + +html_sidebars = { + '**': [ + 'localtoc.html', + 'navigation.html', + 'searchbox.html', + ] +} + + +html_theme_options = { + 'extra_nav_links': OrderedDict([ + ('Home', 'https://http-prompt.com'), + ('Themes', 'https://http-prompt.com/themes'), + ('Gitter', 'https://gitter.im/http-prompt/http-prompt'), + ('GitHub', 'https://github.com/eliangcs/http-prompt'), + ]) +} diff --git a/docs/contributor-guide.rst b/docs/contributor-guide.rst new file mode 100644 index 0000000..c9967f2 --- /dev/null +++ b/docs/contributor-guide.rst @@ -0,0 +1,236 @@ +.. _contributor-guide: + +Contributor Guide +================= + +This document is for developers who want to contribute code to this project. +Any contributions are welcome and greatly appreciated! + +This project follows the common conventions of a Python/GitHub project. So if +you're already an experienced Python/GitHub user, it should be straightforward +for you to set up your development environment and send patches. Generally, the +steps include: + +1. Fork and clone the repo +2. Create a virtualenv for this project +3. Install dependent packages with ``pip install -e .`` +4. Install test dependent packages with ``pip install -r requirements-test.txt`` +5. Make your changes to the code +6. Run tests with ``pytest`` and ``tox`` +7. Commit and push your changes +8. Send a pull request +9. Wait to be reviewed and get merged! + +If you're not familiar with any of the above steps, read the following +instructions. + + +Forking +------- + +*Fork* is a term invented by GitHub. It means copy someone else's project to +your account, so you can make changes without interfering with the original +project. + +To fork HTTP Prompt, just click the **Fork** button on HTTP Prompt's GitHub +project page. Then you clone your fork to your local computer:: + + $ cd ~/Projects + $ git clone git@github.com:{YOUR_USERNAME}/http-prompt.git + +Read `Forking Projects`_ on GitHub to learn more. + + +Working with virtualenv +----------------------- + +*virtualenv* is the de facto standard tool when developing a Python project. +Instead of polluting your system-wide Python installation with different Python +projects, virtualenv creates an isolated Python environment exclusively for a +Python project. + +There are several tools you can use for managing virtualenvs. In this guide, +we'll show you how to use pyenv_ and pyenv-virtualenv_, which is one of the +most popular virtualenv management tools. + +Make sure you have installed pyenv_ and pyenv-virtualenv_ first. + +HTTP Prompt should work on Python 2.6, 2.7, 3.3, 3.4, and 3.5. You can use any +of these Python versions as your development environment, but using the latest +version (3.5.x) is probably the best. You can install the latest Python with +pyenv:: + + $ pyenv install 3.5.2 + +This will install Python 3.5.2 in ``~/.pyenv/versions/3.5.2`` directory. To +create a virtualenv for HTTP Prompt, do:: + + $ pyenv virtualenv 3.5.2 http-prompt + +The command means: create a virtualenv named "http-prompt" based on Python +3.5.2. The virtualenv can be found at ``~/.pyenv/versions/3.5.2/envs/http-prompt``. + +To activate the virtualenv, do:: + + $ pyenv activate http-prompt + +This will switch your Python environment from the system-wide Python to the +virtualenv's (named "http-prompt") Python. + +To go back to the system-wide Python, you have to deactivate the virtualenv:: + + $ pyenv deactivate + +Refer to pyenv_ and pyenv-virtualenv_ if anything else is unclear. + + +Installing Dependent Packages +----------------------------- + +The dependent packages should be installed on a virtualenv, so make sure you +activate your virtualenv first. If not, do:: + + $ pyenv activate http-prompt + +It is also recommended to use the latest version of pip. You can upgrade it +with:: + + $ pip install -U pip + +Install HTTP Prompt with its dependent packages:: + + $ cd ~/Projects/http-prompt + $ pip install -e . + +``pip install -e .`` means install the ``http-prompt`` package in editable mode +(or developer mode). This allows you to edit code directly in +``~/Projects/http-prompt`` without reinstalling the package. Without the ``-e`` +option, the package will be installed to Python's ``site-packages`` directory, +which is not convenient for developing. + + +Installing Test Dependent Packages +---------------------------------- + +Test requirements are placed in a separate file named ``requirements-test.txt``. +To install them, do:: + + $ cd ~/Projects/http-prompt + $ pip install -r requirements-test.txt + + +Making Your Changes +------------------- + +Code Style +~~~~~~~~~~ + +Always lint your code with Flake8_. You can set it up in your code editor or +simply use ``flake8`` in the command line. + +`The Hitchhiker’s Guide to Python`_ provides the best Python coding practices. +We recommend anyone who wants to write good Python code to read it. + +Adding Features +~~~~~~~~~~~~~~~ + +Before you add a new feature, make sure you create an issue making a proposal +first, because you don't want to waste your time on something that the +community don't agree upon. + +Python 2 and 3 Compatibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +HTTP Prompt is compatible with Python 2 and 3. Keep in mind that you're coding +for Python 2 and 3 at the same time. You can use Tox_ (see below) to make sure +the code is runnable on both Python 2 and 3. + + +Running Tests +------------- + +Single Python Version +~~~~~~~~~~~~~~~~~~~~~ + +Make sure your virtualenv is activated. To run tests, do:: + + $ cd ~/Projects/http-prompt + $ pytest + +``pytest`` runs the tests with your virtualenv's Python version. This is good +for fast testing. To test the code against multiple Python versions, you use +Tox_. + +Multiple Python Versions +~~~~~~~~~~~~~~~~~~~~~~~~ + +All the commands in this section should **NOT** be run in a virtualenv. +Deactivate it first if you're in a virtualenv:: + + $ pyenv deactivate + +Make sure you have installed all the Python versions we're targeting. If not, +do:: + + $ pyenv install 2.6.9 + $ pyenv install 2.7.12 + $ pyenv install 3.3.6 + $ pyenv install 3.4.5 + $ pyenv install 3.5.2 + $ pyenv install pypy-5.3.1 + $ pyenv install pypy3-2.4.0 + +To use Tox_ with pyenv_, you have to instruct pyenv to use multiple Python +versions for the project:: + + $ cd ~/Projects/http-prompt + $ pyenv local 3.5.2 3.4.5 3.3.6 2.7.12 2.6.9 pypy-5.3.1 pypy3-2.4.0 + +This will generate a ``.python-version`` in the project directory:: + + $ cat ~/Projects/http-prompt/.python-version + 3.5.2 + 3.4.5 + 3.3.6 + 2.7.12 + 2.6.9 + pypy-5.3.1 + pypy3-2.4.0 + +This tells pyenv_ to choose a Python version based on the above order. In this +case, 3.5.2 is the first choice, so any Python executables (such as ``python`` +and ``pip``) will be automatically mapped to the ones in +``~/.pyenv/versions/3.5.2/bin``. + +We want to run ``tox`` using on Python 3.5.2. Make sure you have installed +Tox_:: + + $ pip install tox + +To run tests, execute ``tox``:: + + $ cd ~/Projects/http-prompt + $ tox + +Tox_ will install the test Python environments in the ``.tox/`` directory in +the project directory, and run the test code against all the Python versions +listed above. + + +Code Review +----------- + +Once you made changes and all the tests pass, push your modified code to your +GitHub account. Submit a pull request (PR) on GitHub for the maintainers to +review. If the patch is good, The maintainers will merge it to the master +branch and ship the new code in the next release. If the patch needs +improvements, we'll give you feedback so you can modify accordingly and +resubmit it to the PR. + + +.. _Flake8: http://flake8.pycqa.org/en/latest/index.html +.. _Forking Projects: https://guides.github.com/activities/forking/ +.. _pyenv-virtualenv: https://github.com/yyuu/pyenv-virtualenv +.. _pyenv: https://github.com/yyuu/pyenv +.. _The Hitchhiker’s Guide to Python: http://docs.python-guide.org/en/latest/ +.. _Tox: https://tox.readthedocs.io/en/latest/ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..48a523c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,68 @@ +HTTP Prompt Documentation +========================= + +HTTP Prompt is an interactive command-line HTTP client featuring autocomplete +and syntax highlighting, built on HTTPie_ and prompt_toolkit_. + +See it in action: + +|Asciinema| + + +Contents +-------- + +.. toctree:: + :maxdepth: 3 + + user-guide + contributor-guide + + +Roadmap +------- + +* Support for advanced HTTPie syntax, e.g, ``field:=json`` and ``field=@file.json`` +* Support for cURL command and raw format preview +* Improve autocomplete +* Python syntax evaluation +* HTTP/2 support + + +User Support +------------ + +We'd love to hear more from our users! Please use the following channels for +bug reports, feature requests, and questions: + +* `GitHub issues`_ +* `Gitter chat room`_ + + +Contributing +------------ + +Are you a developer and interested in contributing to HTTP Prompt? See +:ref:`Contributor Guide `. + + +Thanks +------ + +* HTTPie_: for designing such a user-friendly HTTP CLI +* prompt_toolkit_: for simplifying the work of building an interactive CLI +* Parsimonious_: for the PEG parser used by this project +* pgcli_: for the inspiration of this project +* Contributors_: for improving this project + + +.. |Asciinema| image:: https://asciinema.org/a/96613.png + :target: https://asciinema.org/a/96613?theme=monokai&size=medium&autoplay=1 + +.. _Contributors: https://github.com/eliangcs/http-prompt/graphs/contributors +.. _GitHub issues: https://github.com/eliangcs/http-prompt/issues +.. _Gitter chat room: https://gitter.im/http-prompt/http-prompt +.. _HTTPie: https://httpie.org +.. _Parsimonious: https://github.com/erikrose/parsimonious +.. _pgcli: http://pgcli.com +.. _prompt_toolkit: https://github.com/jonathanslenders/python-prompt-toolkit diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..5f69275 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=HTTPPrompt + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 0000000..c41f374 --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,321 @@ +.. _user-guide: + +User Guide +========== + +Installation +------------ + +Just install it like a regular Python package:: + + $ pip install http-prompt + +You'll probably see some permission errors if you're trying to install it on +the system-wide Python. It isn't recommended. But if that's what you want to +do, you need to ``sudo``:: + + $ sudo pip install http-prompt + +Another alternative is to use ``--user`` option to install the package into +your user directory:: + + $ pip install --user http-prompt + +To upgrade HTTP Prompt, do:: + + $ pip install -U http-prompt + + +Quickstart +---------- + +To start a session, you use the ``http-prompt`` executable: + +.. code-block:: bash + + # Start with the last session or http://localhost:8000 + $ http-prompt + + # Start with the given URL + $ http-prompt http://httpbin.org + + # Start with some initial options + $ http-prompt localhost:8000/api --auth user:pass username=somebody + +Once you're in a session, you can use the following commands. + +To change URL address, use ``cd``: + +.. code-block:: bash + + # Relative URL path + > cd api/v1 + + # Absolute URL + > cd http://localhost/api + +To add headers, querystring, or body parameters, use the syntax as in HTTPie_. +The following are all valid: + +.. code-block:: bash + + > Content-Type:application/json username=john + > 'name=John Doe' apikey==abc + > Authorization:"Bearer auth_token" + +You can also add HTTPie_ options like this: + +.. code-block:: bash + + > --form --auth user:pass + > --verify=no username=jane + +To preview how HTTP Prompt is going to call HTTPie_, do: + +.. code-block:: bash + + > httpie post + http --auth user:pass --form POST http://localhost/api apikey==abc username=john + +You can temporarily override the request parameters by supplying options and +parameters in ``httpie`` command. The overrides won't affect the later +requests. + +.. code-block:: bash + + # No parameters initially + > httpie + http http://localhost + + # Override parameters temporarily + > httpie /api/something page==2 --json + http --json http://localhost/api/something page==2 + + # Current state is not affected by the above overrides + > httpie + http http://localhost + +Since v0.6.0, apart from ``httpie`` command, you can also use ``env`` to print +the current session: + +.. code-block:: bash + + > env + --verify=no + cd http://localhost + page==10 + limit==20 + +To actually send an HTTP request, enter one of the HTTP methods: + +.. code-block:: bash + + > get + > post + > put + > patch + > delete + > head + > options (new in v0.8.0) + +The above HTTP methods also support temporary overriding: + +.. code-block:: bash + + # No parameters initially + > httpie + http http://localhost + + # Send a request with some overrided parameters + > post /api/v1 --form name=jane + + # Current state remains intact + > httpie + http http://localhost + +To remove an existing header, a querystring parameter, a body parameter, or an +HTTPie_ option: + +.. code-block:: bash + + > rm -h Content-Type + > rm -q apikey + > rm -b username + > rm -o --auth + +To reset the session, i.e., clear all parameters and options: + +.. code-block:: bash + + > rm * + +To exit a session, simply enter: + +.. code-block:: bash + + > exit + + +Output Redirection +------------------ + +*New in v0.6.0.* + +You can redirect the output of a command to a file by using the syntax: + +.. code-block:: bash + + # Write output to a file + > COMMAND > /path/to/file + + # Append output to a file + > COMMAND >> /path/to/file + +where ``COMMAND`` can be one of the following: + +* ``env`` +* ``httpie`` +* HTTP actions: ``get``, ``post``, ``put``, ``patch``, ``delete``, ``head`` + + +Saving and Loading Sessions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One of the use cases of output redirection is to save and load sessions, which +is especially useful for team collaboration, where you want to share your +sessions with your team members. + +To save your current session, you redirect the output of ``env`` to a file: + +.. code-block:: bash + + > env > /path/to/file + +To load a saved session, you can use ``source`` or ``exec``. Their only +difference is that ``exec`` wipes out the current session before loading. +Usage: + +.. code-block:: bash + + # Update the current session + > source /path/to/file + + # Overwrite the current session completely + > exec /path/to/file + + +Saving HTTP Respones +~~~~~~~~~~~~~~~~~~~~ + +Printing HTTP responses to the console is good for small text responses. For +larger text or binary data, you may want to save the response to a file. Usage: + +.. code-block:: bash + + # Save http://httpbin.org/image/png to a file + > cd http://httpbin.org/image/png + > get > pig.png + + # Or use this one-liner + > get http://httpbin.org/image/png > pig.png + + +Pipeline +-------- + +*New in v0.7.0.* + +HTTP Prompt supports simplified pipeline syntax, where you can pipe the output +to a shell command: + +.. code-block:: bash + + # Replace 'localhost' to '127.0.0.1' + > httpie POST http://localhost | sed 's/localhost/127.0.0.1/' + http http://127.0.0.1 + + # Only print the line that contains 'User-Agent' using grep + > get http://httpbin.org/get | grep 'User-Agent' + "User-Agent": "HTTPie/0.9.6" + +On macOS, you can even copy the result to the clipboard using ``pbcopy``: + +.. code-block:: bash + + # Copy the HTTPie command to the clipboard (macOS only) + > httpie | pbcopy + +Another cool trick is to use jq_ to parse JSON data: + +.. code-block:: bash + + > get http://httpbin.org/get | jq '.headers."User-Agent"' + "HTTPie/0.9.6" + +**Note**: Syntax with multiple pipes is not supported currently. + + +Shell Substitution +------------------ + +*New in v0.7.0.* + +Shell substitution happens when you put a shell command between two backticks +like ``\`...\```. This syntax allows you compute a value from the shell +environment and assign the value to a parameter:: + + # Set date to current time + > date==`date -u +"%Y-%m-%d %H:%M:%S"` + > httpie + http http://localhost:8000 'date==2016-10-08 09:45:00' + + # Get password from a file. Suppose the file has a content of + # "secret_api_key". + > password==`cat ./apikey.txt` + > httpie + http http://localhost:8000 apikey==secret_api_key + + +Configuration +------------- + +*New in v0.4.0.* + +When launched for the first time, HTTP Prompt creates a user config file at +``$XDG_CONFIG_HOME/http-prompt/config.py`` (or ``%LOCALAPPDATA%/http-prompt/config.py`` +on Windows). By default, it's ``~/.config/http-prompt/config.py`` (or +``~/AppData/Local/http-prompt/config.py``). + +``config.py`` is a Python module with all the available options you can +customize. Don't worry. You don't need to know Python to edit it. Just open it +up with a text editor and follow the guidance inside. + + +Persistent Context +------------------ + +*New in v0.4.0.* + +HTTP Prompt keeps a data structure called *context* to represent your current +session. Every time you enter a command modifying your context, HTTP Prompt +saves the context to your filesystem, enabling you to resume your previous +session when you restart ``http-prompt``. + +The last saved context is located at ``$XDG_DATA_HOME/http-prompt/context.hp`` +(or ``%LOCALAPPDATA%/http-prompt/context.hp`` on Windows). By default, it's +``~/.local/share/http-prompt/context.hp`` (or ``~/AppData/Local/http-prompt/context.hp``). + +As context data may contain sensitive data like API keys, you should keep the +user data directory private. By default, HTTP Prompt sets the modes of +``$XDG_DATA_HOME/http-prompt`` to ``rwx------`` (i.e., ``700``) so that the +only person who can read it is the owner (you). + +**Note for users of older versions**: Since 0.6.0, HTTP Prompt only stores the +last context instead of grouping multiple contexts by hostnames and ports like +it did previously. We changed the behavior because the feature can be simply +replaced by ``env``, ``exec`` and ``source`` commands. See the discussion in +`issue #70 `_ for detail. + + +.. _HTTPie: https://github.com/jkbrzt/httpie +.. _jq: https://stedolan.github.io/jq/ From 4154249c98229c01a0e64f85b2e8322a9139b4c7 Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Fri, 23 Dec 2016 00:53:54 +0800 Subject: [PATCH 2/6] Add documentation to contributor guide --- docs/contributor-guide.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/contributor-guide.rst b/docs/contributor-guide.rst index c9967f2..7ff41ef 100644 --- a/docs/contributor-guide.rst +++ b/docs/contributor-guide.rst @@ -145,6 +145,20 @@ HTTP Prompt is compatible with Python 2 and 3. Keep in mind that you're coding for Python 2 and 3 at the same time. You can use Tox_ (see below) to make sure the code is runnable on both Python 2 and 3. +Documentation +~~~~~~~~~~~~~ + +Documentation is written in Sphinx_. To build documentation, you need to +install Sphinx_ first:: + + $ pip install sphinx + +To build and view documentation in HTML, do:: + + $ cd ~/Projects/http-prompt/docs + $ make html + $ open _build/html/index.html + Running Tests ------------- @@ -232,5 +246,6 @@ resubmit it to the PR. .. _Forking Projects: https://guides.github.com/activities/forking/ .. _pyenv-virtualenv: https://github.com/yyuu/pyenv-virtualenv .. _pyenv: https://github.com/yyuu/pyenv +.. _Sphinx: http://www.sphinx-doc.org/ .. _The Hitchhiker’s Guide to Python: http://docs.python-guide.org/en/latest/ .. _Tox: https://tox.readthedocs.io/en/latest/ From 27f6460fbd8bec1e959c7ceea9abd53837543828 Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Fri, 23 Dec 2016 01:45:40 +0800 Subject: [PATCH 3/6] Play asciinema faster --- README.rst | 2 +- docs/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index bc40531..7857fb8 100644 --- a/README.rst +++ b/README.rst @@ -32,7 +32,7 @@ For find out more, please visit the following links: :target: https://gitter.im/http-prompt/http-prompt .. |Asciinema| image:: https://asciinema.org/a/96613.png - :target: https://asciinema.org/a/96613?theme=monokai&size=medium&autoplay=1 + :target: https://asciinema.org/a/96613?theme=monokai&size=medium&autoplay=1&speed=2 .. _HTTPie: https://httpie.org .. _prompt_toolkit: https://github.com/jonathanslenders/python-prompt-toolkit diff --git a/docs/index.rst b/docs/index.rst index 48a523c..20cf745 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,7 +57,7 @@ Thanks .. |Asciinema| image:: https://asciinema.org/a/96613.png - :target: https://asciinema.org/a/96613?theme=monokai&size=medium&autoplay=1 + :target: https://asciinema.org/a/96613?theme=monokai&size=medium&autoplay=1&speed=2 .. _Contributors: https://github.com/eliangcs/http-prompt/graphs/contributors .. _GitHub issues: https://github.com/eliangcs/http-prompt/issues From 6903d104b0b7bfe01e7ce168e9d2ae7860eb05f4 Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Fri, 23 Dec 2016 02:03:48 +0800 Subject: [PATCH 4/6] Hide home for now --- README.rst | 3 +-- docs/conf.py | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 7857fb8..a282744 100644 --- a/README.rst +++ b/README.rst @@ -10,8 +10,7 @@ and syntax highlighting, built on HTTPie_ and prompt_toolkit_. For find out more, please visit the following links: -* Home: https://http-prompt.com -* Documentation: https://docs.http-prompt.com +* Documentation: http://docs.http-prompt.com * GitHub: https://github.com/eliangcs/http-prompt * Gitter: https://gitter.im/http-prompt/http-prompt diff --git a/docs/conf.py b/docs/conf.py index b379055..ee31ce4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -168,8 +168,8 @@ html_theme_options = { 'extra_nav_links': OrderedDict([ - ('Home', 'https://http-prompt.com'), - ('Themes', 'https://http-prompt.com/themes'), + # ('Home', 'http://http-prompt.com'), + # ('Themes', 'https://http-prompt.com/themes'), ('Gitter', 'https://gitter.im/http-prompt/http-prompt'), ('GitHub', 'https://github.com/eliangcs/http-prompt'), ]) From 6be52afb721d022a2fa2b86293180860c91063f0 Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Fri, 23 Dec 2016 21:10:10 +0800 Subject: [PATCH 5/6] Add analytics code to docs --- docs/_templates/analytics.html | 4 ++++ docs/_templates/layout.html | 8 ++++++++ 2 files changed, 12 insertions(+) create mode 100644 docs/_templates/analytics.html create mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/analytics.html b/docs/_templates/analytics.html new file mode 100644 index 0000000..388e206 --- /dev/null +++ b/docs/_templates/analytics.html @@ -0,0 +1,4 @@ + diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..0a964f4 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,8 @@ +{%- extends "!layout.html" %} + +{% block extrahead %} + {{ super() }} + {% if READTHEDOCS %} + {% include "analytics.html" %} + {% endif %} +{% endblock %} From 977dc9ac56cb703781c2572a82ea76154106a866 Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Fri, 23 Dec 2016 22:10:46 +0800 Subject: [PATCH 6/6] Add docs badge --- README.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index a282744..896e594 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ HTTP Prompt =========== -|PyPI| |Travis| |Appveyor| |Coverage| |Gitter| +|PyPI| |Docs| |Travis| |Appveyor| |Coverage| |Gitter| HTTP Prompt is an interactive command-line HTTP client featuring autocomplete and syntax highlighting, built on HTTPie_ and prompt_toolkit_. @@ -18,6 +18,9 @@ For find out more, please visit the following links: .. |PyPI| image:: https://img.shields.io/pypi/v/http-prompt.svg :target: https://pypi.python.org/pypi/http-prompt +.. |Docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat + :target: http://docs.http-prompt.com/en/latest/?badge=latest + .. |Travis| image:: https://api.travis-ci.org/eliangcs/http-prompt.svg?branch=master :target: https://travis-ci.org/eliangcs/http-prompt