Merge pull request #1688 from NoahGorny/docs

Basic ReadTheDocs

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+sphinx:
+  builder: htmldir
+  configuration: docs/conf.py
+
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt

.travis.yml

@@ -22,6 +22,15 @@ cache:
 
 jobs:
   include:
+  - language: python
+    python: 3.8
+    name: docs
+    dist: bionic
+    install:
+      pip3 install -r docs/requirements.txt;
+    script:
+      sphinx-build -W -b html docs docs/_build/html;
+
   - language: go
     go: "1.14"
     name: pre-commit lint

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+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)

docs/commands/doctor.rst

@@ -0,0 +1,20 @@
+.. _doctor:
+
+Bash-it doctor
+^^^^^^^^^^^^^^
+
+If you encounter problems with any part of Bash-it, run the following command:
+
+.. code-block:: bash
+
+   bash-it doctor
+
+This will reload your bash profile and print out logs of various parts in Bash-it.
+Note that this command at default will print all logs, including debug logs.
+You can call it like this:
+
+.. code-block:: bash
+
+   bash-it doctor [errors/warnings/all]
+
+In order to get wanted verbosity.

docs/commands/index.rst

@@ -0,0 +1,15 @@
+.. _commands:
+
+Bash-it Commands
+================
+
+**Bash-it** boasts a wide range of available commands.
+You should be familiar with them in order to fully utilize Bash-it.
+
+.. toctree::
+   :maxdepth: 1
+
+   update
+   search
+   reload
+   doctor

docs/commands/reload.rst

@@ -0,0 +1,10 @@
+.. _reload:
+
+Bash-it reload
+^^^^^^^^^^^^^^
+
+Bash-it creates a ``reload`` alias that makes it convenient to reload
+your Bash profile when you make changes.
+
+Additionally, if you export ``BASH_IT_AUTOMATIC_RELOAD_AFTER_CONFIG_CHANGE`` as a non-null value,
+Bash-it will automatically reload itself after activating or deactivating plugins, aliases, or completions.

docs/commands/search.rst

@@ -0,0 +1,59 @@
+.. _searching:
+
+Bash-it search
+--------------
+
+If you need to quickly find out which of the plugins, aliases or completions are available for a specific framework, programming language, or an environment, you can *search* for multiple terms related to the commands you use frequently.
+Search will find and print out modules with the name or description matching the terms provided.
+
+Syntax
+^^^^^^
+
+.. code-block:: bash
+
+     bash-it search term1 [[-]term2] [[-]term3]....
+
+As an example, a ruby developer might want to enable everything related to the commands such as ``ruby``\ , ``rake``\ , ``gem``\ , ``bundler``\ , and ``rails``.
+Search command helps you find related modules so that you can decide which of them you'd like to use:
+
+.. code-block:: bash
+
+   ❯ bash-it search ruby rake gem bundle irb rails
+         aliases:  bundler rails
+         plugins:  chruby chruby-auto ruby
+     completions:  bundler gem rake
+
+Currently enabled modules will be shown in green.
+
+Searching with Negations
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can prefix a search term with a "-" to exclude it from the results.
+In the above example, if we wanted to hide ``chruby`` and ``chruby-auto``\ ,
+we could change the command as follows:
+
+.. code-block:: bash
+
+   ❯ bash-it search ruby rake gem bundle irb rails -chruby
+         aliases:  bundler rails
+         plugins:  ruby
+     completions:  bundler gem rake
+
+Using Search to Enable or Disable Components
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By adding a ``--enable`` or ``--disable`` to the search command, you can automatically enable all modules that come up as a result of a search query.
+This could be quite handy if you like to enable a bunch of components related to the same topic.
+
+Disabling ASCII Color
+^^^^^^^^^^^^^^^^^^^^^
+
+To remove non-printing non-ASCII characters responsible for the coloring of the search output, you can set environment variable ``NO_COLOR``.
+Enabled components will then be shown with a checkmark:
+
+.. code-block:: bash
+
+   ❯ NO_COLOR=1 bash-it search ruby rake gem bundle irb rails -chruby
+         aliases  =>   ✓bundler ✓rails
+         plugins  =>   ✓ruby
+     completions  =>   bundler gem rake

docs/commands/update.rst

@@ -0,0 +1,38 @@
+.. _update:
+
+Bash-it update
+^^^^^^^^^^^^^^
+
+To update Bash-it to the latest stable version, simply run:
+
+.. code-block:: bash
+
+   bash-it update stable
+
+If you want to update to the latest dev version (directly from master), run:
+
+.. code-block:: bash
+
+   bash-it update dev
+
+If you want to update automatically and unattended, you can add the optional
+``-s/--silent`` flag, for example:
+
+.. code-block:: bash
+
+   bash-it update dev --silent
+
+.. _migrate:
+
+Bash-it migrate
+^^^^^^^^^^^^^^^
+
+If you are using an older version of Bash-it, it's possible that some functionality has changed, or that the internal structure of how Bash-it organizes its functionality has been updated.
+For these cases, we provide a ``migrate`` command:
+
+.. code-block:: bash
+
+   bash-it migrate
+
+This command will automatically migrate the Bash-it structure to the latest version.
+The ``migrate`` command is run automatically if you run the ``update``\ , ``enable`` or ``disable`` commands.

docs/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Bash-it'
+copyright = '2020, Bash-it Team'
+author = 'Bash-it Team'
+
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# 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_rtd_theme'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- 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 = 'sphinx_rtd_theme'
+
+# 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']

docs/contributing.rst

@@ -0,0 +1,108 @@
+.. _contributing:
+
+Contribution Guidelines
+=======================
+
+When contributing a new feature, a bug fix, a new theme, or any other change to Bash-it, please consider the following guidelines.
+Most of this is common sense, but please try to stick to the conventions listed here.
+
+Issues
+------
+
+
+* When opening a new issue in the issue tracker, please include information about which *Operating System* you're using, and which version of *Bash*.
+* In many cases, it also makes sense to show which Bash-it plugins you are using.
+  This information can be obtained using ``bash-it show plugins``.
+* If the issue happens while loading Bash-it, please also include your ``~/.bash_profile`` or ``~/.bashrc`` file,
+  as well as the install location of Bash-it (default should be ``~/.bash_it``\ ).
+* When reporting a bug or requesting a new feature, consider providing a Pull Request that fixes the issue or can be used as a starting point for the new feature.
+  Don't be afraid, most things aren't that complex...
+
+Pull Requests
+-------------
+
+
+* Fork the Bash-it repo, create a new feature branch from *master* and apply your changes there.
+  Create a *Pull Request* from your feature branch against Bash-it's *master* branch.
+* Limit each Pull Request to one feature.
+  Don't bundle multiple features/changes (e.g. a new *Theme* and a fix to an existing plugin) into a single Pull Request - create one PR for the theme, and a separate PR for the fix.
+* For complex changes, try to *squash* your changes into a single commit before
+  pushing code. Once you've pushed your code and opened a PR, please refrain
+  from force-pushing changes to the PR branch – remember, Bash-it is a
+  distributed project and your branch may be in use already.
+* When in doubt, open a PR with too many commits. Bash-it is a learning project
+  for everyone involved. Showing your work provides a great history for folks
+  to learn what works and what didn't.
+
+Code Style
+----------
+
+
+* Try to stick to the existing code style. Please don't reformat or change the syntax of existing code simply because you don't like that style.
+* Indentation is using spaces, not tabs. Most of the code is indented with 2 spaces, some with 4 spaces. Please try to stick to 2 spaces.
+  If you're using an editor that supports `EditorConfig <http://EditorConfig.org>`_\ , the editor should automatically use the settings defined in Bash-it's `.editorconfig file <.editorconfig>`_.
+* When creating new functions, please use a dash ("-") to separate the words of the function's name, e.g. ``my-new-function``.
+  Don't use underscores, e.g. ``my_new_function``.
+* Internal functions that aren't to be used by the end user should start with an underscore, e.g. ``_my-new-internal-function``.
+* Use the provided meta functions to document your code, e.g. ``about-plugin``\ , ``about``\ , ``group``\ , ``param``\ , ``example``.
+  This will make it easier for other people to use your new functionality.
+  Take a look at the existing code for an example (e.g. `the base plugin <plugins/available/base.plugin.bash>`_\ ).
+* When adding files, please use the existing file naming conventions, e.g. plugin files need to end in ``.plugin.bash``.
+  This is important for the installation functionality.
+* When using the ``$BASH_IT`` variable, please always enclose it in double quotes to ensure that the code also works when Bash-it is installed in a directory that contains spaces in its name: ``for f in "${BASH_IT}/plugins/available"/*.bash ; do echo "$f" ; done``
+* Bash-it supports Bash 3.2 and higher. Please don't use features only available in Bash 4, such as associative arrays.
+
+Unit Tests
+----------
+
+When adding features or making changes/fixes, please run our growing unit test suite to ensure that you did not break existing functionality.
+The test suite does not cover all aspects of Bash-it, but please run it anyway to verify that you did not introduce any regression issues.
+
+Any code pushed to GitHub as part of a Pull Request will automatically trigger a continuous integration build on `Travis CI <https://travis-ci.org/Bash-it/bash-it>`_\ , where the test suite is run on both Linux and macOS.
+The Pull Request will then show the result of the Travis build, indicating whether all tests ran fine, or whether there were issues.
+Please pay attention to this, Pull Requests with build issues will not be merged.
+
+Adding new functionality or changing existing functionality is a good opportunity to increase Bash-it's test coverage.
+When you're changing the Bash-it codebase, please consider adding some unit tests that cover the new or changed functionality.
+Ideally, when fixing a bug, a matching unit test that verifies that the bug is no longer present, is added at the same time.
+
+To run the test suite, simply execute the following in the directory where you cloned Bash-it:
+
+.. code-block:: bash
+
+   test/run
+
+This command will ensure that the `Bats Test Framework <https://github.com/bats-core/bats-core>`_ is available in the local ``test_lib`` directory (Bats is included as a Git submodule) and then run the test suite found in the `test <test>`_ folder.
+The test script will execute each test in turn, and will print a status for each test case.
+
+When adding new test cases, please take a look at the existing test cases for examples.
+
+The following libraries are used to help with the tests:
+
+
+* Test Framework: https://github.com/bats-core/bats-core
+* Support library for Bats-Assert: https://github.com/ztombol/bats-support
+* General ``assert`` functions: https://github.com/ztombol/bats-assert
+* File ``assert`` functions: https://github.com/ztombol/bats-file
+
+When verifying test results, please try to use the ``assert`` functions found in these libraries.
+
+Features
+--------
+
+
+* When adding new completions or plugins, please don't simply copy existing tools into the Bash-it codebase, try to load/integrate the tools instead.
+  An example is using ``nvm``\ : Instead of copying the existing ``nvm`` script into Bash-it, the ``nvm.plugin.bash`` file tries to load an existing installation of ``nvm``.
+  This means an additional step for the user (installing ``nvm`` from its own repo, or through a package manager),
+  but it will also ensure that ``nvm`` can be upgraded in an easy way.
+
+.. _contributing_theme:
+
+Themes
+------
+
+
+* When adding a new theme, please include a screenshot and a short description about what makes this theme unique in the Pull Request's description field.
+  Please do not add theme screenshots to the repo itself, as they will add unnecessary bloat to the repo.
+  The project's Wiki has a *Themes* page where you can add a screenshot if you want.
+* Ideally, each theme's folder should contain a ``README.md`` file describing the theme and its configuration options.

docs/custom.rst

@@ -0,0 +1,18 @@
+.. _custom:
+
+Custom Content
+--------------
+
+For custom scripts, and aliases, just create the following files (they'll be ignored by the git repo):
+
+
+* ``aliases/custom.aliases.bash``
+* ``completion/custom.completion.bash``
+* ``lib/custom.bash``
+* ``plugins/custom.plugins.bash``
+* ``custom/themes/<custom theme name>/<custom theme name>.theme.bash``
+
+Anything in the custom directory will be ignored, with the exception of ``custom/example.bash``.
+
+Alternately, if you would like to keep your custom scripts under version control, you can set ``BASH_IT_CUSTOM`` in your ``~/.bashrc`` to another location outside of the ``$BASH_IT`` folder.
+In this case, any ``*.bash`` file under every directory below ``BASH_IT_CUSTOM`` folder will be used.