Skip to content

Commit a06dbea

Browse files
committed
Merge pull request #156 from tony/doc-releases
Update sphinx docs for libtmux, releases
2 parents 8514a56 + f07d0cf commit a06dbea

21 files changed

+271
-1794
lines changed

CHANGES

Lines changed: 164 additions & 294 deletions
Large diffs are not rendered by default.

README.rst

Lines changed: 58 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
tmuxp, a novel approach to manage `tmux(1)`_ (>= 1.8) workspaces through
2-
`python objects`_, JSON or YAML.
1+
tmuxp, tmux session manager. built on `libtmux`_.
32

43
|pypi| |docs| |build-status| |coverage| |license|
54

@@ -8,37 +7,61 @@ tmuxp, a novel approach to manage `tmux(1)`_ (>= 1.8) workspaces through
87
:width: 45%
98
:align: center
109

11-
How tmuxp helps you tmux:
12-
13-
- Save your most common tmux session layouts in JSON or YAML. See
14-
a `simple`_ or `very elaborate`_ configuration.
15-
- Store layouts personally (``~/.tmuxp``) or include in your project,
16-
see ``~/.tmuxp.{yaml,json}``. See the `author's tmuxp configs`_ and the
17-
the projects' `tmuxp.yaml`_.
18-
- `Freeze`_ the layout of live sessions.
19-
- Automate running such as sourcing into a `virtualenv`_. The configuration
20-
also supports per window commands where all panes inherit commands. See
21-
`Examples`_.
22-
- Run a bootstrapping script to check environment / install dependencies /
23-
setup project before loading starts so your development works across
24-
systems. See this projects `bootstrap_env.py`_ and `before_script`_ example.
25-
- Load tmux sessions in the background by passing ``-d`` flag.
26-
- Load multiple tmux configurations ``tmuxp load config1.yaml
27-
config2.yaml``.
28-
- Switch sessions from inside a current tmux session. tmuxp will detect
29-
if you're in a session and offer to ``switch-client`` for you.
30-
- Offer to re-attach a tmux session if your config is already loaded.
31-
- For more things you can do with tmuxp, see `Examples`_.
32-
- CLI auto-completion with `bash, zsh and tcsh`_.
33-
- Use as a `python library`_, see the `python API quickstart`_.
34-
- Well tested a gain against live tmux (1.8+ and git).
35-
See `travis.yml`_, `tmuxp on Travis CI`_ and `testing`_ page.
36-
- `Import`_ configs `teamocil`_ and `tmuxinator`_.
37-
- Thorough `Documentation`_ (also in `中文`_), `Source`_,
38-
`Commands`_, `Internals`_.
39-
- and `much, much more`_.
40-
41-
Ready to begin? See the `Quickstart`_.
10+
Load a tmux session
11+
-------------------
12+
13+
Load tmux sessions via json and YAML, `tmuxinator`_ and
14+
`teamocil`_ style.
15+
16+
.. code-block:: yaml
17+
18+
session_name: 4-pane-split
19+
windows:
20+
- window_name: dev window
21+
layout: tiled
22+
shell_command_before:
23+
- cd ~/
24+
panes:
25+
- shell_command:
26+
- cd /var/log
27+
- ls -al | grep \.log
28+
- pwd
29+
- pwd
30+
- pwd
31+
32+
Save as ``mysession.yaml``. And load:
33+
34+
.. code-block:: sh
35+
36+
$ tmuxp load ./mysession.yaml
37+
38+
`simple`_, `very elaborate`_ config examples
39+
40+
Store configs in (``~/.tmuxp``) or include in your project as
41+
``~/.tmuxp.{yaml,json}``. See `author's tmuxp configs`_ and the
42+
the projects' `tmuxp.yaml`_.
43+
44+
bootstrap project dependencies before loading tmux. See the
45+
`bootstrap_env.py`_ and `before_script`_ example
46+
47+
Load sessions in the background by passing ``-d`` flag
48+
49+
Freeze a tmux session
50+
---------------------
51+
52+
.. code-block:: sh
53+
54+
$ tmuxp freeze
55+
56+
See more about `freezing tmux`_ sessions.
57+
58+
Docs / Reading material
59+
-----------------------
60+
61+
See the `Quickstart`_.
62+
63+
`Documentation`_ homepage (also in `中文`_)
64+
4265
Want to learn more about tmux itself? Read `The Tao of Tmux`_.
4366

4467
.. _tmuxp on Travis CI: http://travis-ci.org/tony/tmuxp
@@ -55,20 +78,17 @@ Want to learn more about tmux itself? Read `The Tao of Tmux`_.
5578
.. _tmuxinator: https://github.com/aziz/tmuxinator
5679
.. _teamocil: https://github.com/remiprev/teamocil
5780
.. _Examples: http://tmuxp.readthedocs.org/en/latest/examples.html
58-
.. _Freeze: http://tmuxp.readthedocs.org/en/latest/cli.html#freeze-sessions
81+
.. _freezing tmux: http://tmuxp.readthedocs.org/en/latest/cli.html#freeze-sessions
5982
.. _bootstrap_env.py: https://github.com/tony/tmuxp/blob/master/bootstrap_env.py
60-
.. _Import: http://tmuxp.readthedocs.org/en/latest/cli.html#import
6183
.. _travis.yml: http://tmuxp.readthedocs.org/en/latest/developing.html#travis-ci
6284
.. _testing: http://tmuxp.readthedocs.org/en/latest/developing.html#test-runner
6385
.. _python objects: http://tmuxp.readthedocs.org/en/latest/api.html#api
6486
.. _tmuxp.yaml: https://github.com/tony/tmuxp/blob/master/.tmuxp.yaml
6587
.. _simple: http://tmuxp.readthedocs.org/en/latest/examples.html#short-hand-inline
6688
.. _very elaborate: http://tmuxp.readthedocs.org/en/latest/examples.html#super-advanced-dev-environment
67-
.. _bash, zsh and tcsh: http://tmuxp.readthedocs.org/en/latest/cli.html#bash-completion
68-
.. _much, much more: http://tmuxp.readthedocs.org/en/latest/about.html#minor-tweaks
6989
.. _Quickstart: http://tmuxp.readthedocs.org/en/latest/quickstart.html
70-
.. _Internals: http://tmuxp.readthedocs.org/en/latest/internals.html
7190
.. _Commands: http://tmuxp.readthedocs.org/en/latest/cli.html
91+
.. _libtmux: https://github.com/tony/libtmux
7292

7393
Project details
7494
---------------

TODO

Lines changed: 1 addition & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -2,134 +2,6 @@
22
TODO
33
====
44

5-
.. _0.1 milestone:
6-
7-
Milestone 0.1
8-
-------------
9-
10-
Done
11-
""""
12-
13-
- `Issue #25`_ - ``focus: true`` not working in panes.
14-
- `Issue #15`_ - Pane ordering
15-
- `Issue #21`_ - Python 2.6 errors with directories in unit tests
16-
- ``shell_command_before`` for `teamocil`_.
17-
- `teamocil`_ and `tmuxinator`_ import support for blank panes
18-
- Add help docs to CLI commands and options.
19-
- tmuxp -L and -S autocomplete to correct server ``socket-name`` and
20-
``socket-path``.
21-
- Get `sphinx-argparse`_ in good enough shape for docs.
22-
- Rename functions
23-
- ``util.version()`` to ``util.has_required_tmux_version()``. (done)
24-
- ``config.check_consistency()`` to ``config.validate_schema()``. (done)
25-
- Python 2.6 support
26-
- Remove doc for ``run_tests.py`` visual test runner. Just have
27-
instruction for running test builder package.
28-
- tmuxp freeze:
29-
30-
- offer to save ``session_name`` as default file if filename
31-
doesn't already exist in config dir.
32-
- Remove -zsh command, python, etc if just in shell.
33-
- Assure ``$ tmuxp freeze`` works with ``start_directory`` and does not
34-
return commands with dir and no CD's. (esp with zsh).
35-
36-
.. _Issue #15: https://github.com/tony/tmuxp/issues/15
37-
.. _Issue #21: https://github.com/tony/tmuxp/issues/21
38-
.. _Issue #25: https://github.com/tony/tmuxp/issues/25
39-
40-
.. _milestone 0.2:
41-
42-
Milestone 0.2
43-
-------------
44-
45-
Major
46-
"""""
47-
48-
- Fix inconsistencies / syncing with ``.get`` on Windows and panes. Always
49-
get freshest data.
50-
- Validate the data types passed back and forth between options and pane,
51-
window, session proprties. (Create a util method that maps key values to
52-
a type).
53-
- Unit test the above.
54-
55-
- ``tmuxp freeze`` add autogenerated command to yaml configs (won't work w/ json)
56-
- `pep8`_, `pep257`_ for tests. (ongoing)
57-
- if no ``window_name`` in config, option ``automatic_rename: on`` by
58-
default and test.
59-
- example of doctest/usage example of creating a new tmux session from
60-
object
61-
- example of accessing a current tmux session from object
62-
- example of loading a tmux session from a :py:obj:``dict``. example of
63-
the schema.
64-
- code examples in docs
65-
- remove duplicated code in ``tmuxp.cli``.
66-
- Determine the workflow for ``$ tmuxp load filename`` for sure. Document
67-
it.
68-
- Handle case where switching client via ``$ tmuxp load`` or
69-
``$ tmuxp attach-session`` into another socket may cause an error.
70-
- Fix issue where tmuxp freeze with exotic ``PS1``'s cause strange
71-
outputs.
72-
- If session name for ``$ tmuxp freeze`` has spaces, replace whitespace
73-
with dashes.
74-
- Test and ensure correct pane. https://github.com/tony/tmuxp/issues/15.
75-
- :ref:`about_tmux` page.
76-
77-
.. _milestone 0.3:
78-
79-
Milestone 0.3
80-
-------------
81-
82-
- Automatically grab ``[-L socket-name]`` and ``[-S socket-path]``
83-
from where tmuxp was ran. ``os.environ.get('$TMUX')``.
84-
- Automatically grab current sesession, window, session from where
85-
script is ran. ``$ tmuxp kill-window`` should kill current window.
86-
87-
Or, As an alternative, create a mapping that pipes commands right into
88-
tmux like a layer cake.
89-
- $ tmuxp shortened CLI completion:
90-
- <session-name>
91-
- <config-file (minus extension)> yaml, json
92-
93-
- current dir
94-
- config dir
95-
96-
Will be able to attach sessions, load configs without an additional
97-
command. If ``~/.tmuxp/hello.yaml`` exists,
98-
99-
``tmuxp <tab>`` will tab-complete and allow ``$ tmuxp hello`` to load
100-
the yaml config.
101-
102-
If ``~/.tmuxp/hello.json`` exists also, 'hello.json' and 'hello.yaml'
103-
will be available.
104-
105-
If ``.tmuxp.yaml`` exists in current directory, ``.`` will be an
106-
option. If ``.tmuxp.json`` exists also, ``.tmuxp.json`` and
107-
``.tmuxp.yaml`` will have to be entered.
108-
109-
If ``hello.json`` exists in config directory and ``hello`` is a session
110-
name, autocomplete will offer both, ``hello`` attaches that session,
111-
``hello.json`` will attempt to load the file (which may have a
112-
different ``session_name``. If the filename and session name are the
113-
same, it will still offer to attach.
114-
115-
``$ tmuxp .<tab>`` will start autocompletion searching for YAML and
116-
JSON configs in cwd, as will ``$ tmuxp ..<tab>`` and ``$ tmuxp /``.
117-
118-
``$ tmuxp path/to/dir`` should scan for loading .tmuxp.yaml and
119-
.tmuxp.json files.
120-
- ``/path/to/project/.tmuxp/*.yaml`` for projects with multiple
121-
workspaces.
122-
- Support for session, window, pane ``requires`` that supports path to
123-
shell script returning an exit code and ``only_if``. Will verify before
124-
creation of session, window, pane. Can be used for assuring a tmuxp
125-
workspace sets up a development environment.
126-
127-
128-
.. _pep257: http://www.python.org/dev/peps/pep-0257/
129-
.. _pep8: http://www.python.org/dev/peps/pep-0008/
130-
.. _teamocil: https://github.com/remiprev/teamocil
131-
.. _tmuxinator: https://github.com/aziz/tmuxinator
132-
.. _sphinx-argparse: https://github.com/tony/sphinx-argparse
133-
5+
- Cleared to do on 2016-05-23
1346

1357
.. todo:: vim: set filetype=rst:

doc/_static/tmuxp.css

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,7 @@ div.sidebar .sidebar-title {
1212
form.navbar-form {
1313
padding: 0px 10px;
1414
}
15+
16+
div#changelog > div.section > ul > li > p:only-child {
17+
margin-bottom: 0;
18+
}

doc/api.rst

Lines changed: 0 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -10,79 +10,20 @@ API Reference
1010

1111
.. module:: tmuxp
1212

13-
Server Object
14-
-------------
15-
16-
.. autoclass:: Server
17-
:members:
18-
:inherited-members:
19-
:private-members:
20-
:show-inheritance:
21-
:member-order: bysource
22-
23-
Session Object
24-
--------------
25-
26-
.. autoclass:: Session
27-
:members:
28-
:inherited-members:
29-
:private-members:
30-
:show-inheritance:
31-
:member-order: bysource
32-
33-
Window Object
34-
-------------
35-
36-
.. autoclass:: Window
37-
:members:
38-
:inherited-members:
39-
:private-members:
40-
:show-inheritance:
41-
:member-order: bysource
42-
43-
Pane Object
44-
-----------
45-
46-
.. autoclass:: Pane
47-
:members:
48-
:inherited-members:
49-
:private-members:
50-
:show-inheritance:
51-
:member-order: bysource
52-
5313
Internals
5414
---------
5515

56-
.. autoclass:: tmuxp.util.TmuxRelationalObject
57-
:members:
58-
59-
.. autoclass:: tmuxp.util.TmuxMappingObject
60-
:members:
61-
62-
.. autoclass:: tmuxp.util.tmux_cmd
63-
64-
.. automethod:: tmuxp.util.has_required_tmux_version
65-
66-
.. automethod:: tmuxp.util.oh_my_zsh_auto_title
67-
68-
.. automethod:: tmuxp.util.which
69-
7016
.. automethod:: tmuxp.util.run_before_script
7117

72-
.. automethod:: tmuxp.util.is_version
73-
7418
Command Line
7519
------------
7620

7721
.. automethod:: tmuxp.cli.startup
78-
7922
.. automethod:: tmuxp.cli.prompt
8023
.. automethod:: tmuxp.cli.prompt_bool
8124
.. automethod:: tmuxp.cli.prompt_choices
82-
8325
.. automethod:: tmuxp.cli.setup_logger
8426
.. automethod:: tmuxp.cli.get_parser
85-
8627
.. automethod:: tmuxp.cli.load_workspace
8728

8829
Configuration
@@ -92,9 +33,7 @@ Finding
9233
"""""""
9334

9435
.. automethod:: tmuxp.config.is_config_file
95-
9636
.. automethod:: tmuxp.config.in_dir
97-
9837
.. automethod:: tmuxp.config.in_cwd
9938

10039
Import and export
@@ -123,25 +62,10 @@ Workspace Builder
12362
Exceptions
12463
----------
12564

126-
.. autoexception:: tmuxp.exc.TmuxpException
127-
128-
.. autoexception:: tmuxp.exc.TmuxSessionExists
129-
13065
.. autoexception:: tmuxp.exc.EmptyConfigException
13166

13267
.. autoexception:: tmuxp.exc.ConfigError
13368

13469
.. autoexception:: tmuxp.exc.BeforeLoadScriptError
13570

13671
.. autoexception:: tmuxp.exc.BeforeLoadScriptNotExists
137-
138-
Test tools
139-
----------
140-
141-
.. automethod:: tmuxp.testsuite.helpers.get_test_session_name
142-
143-
.. automethod:: tmuxp.testsuite.helpers.get_test_window_name
144-
145-
.. automethod:: tmuxp.testsuite.helpers.temp_session
146-
147-
.. automethod:: tmuxp.testsuite.helpers.temp_window

0 commit comments

Comments
 (0)