Eclectic Media Git eclecti_deploy / 338ef32
Added full documentation for manpages Ariana Giroux 9 months ago
4 changed file(s) with 192 addition(s) and 11 deletion(s). Raw diff Collapse all Expand all
143143
144144 # -- Options for manual page output ------------------------------------------
145145
146 # man_show_urls = True
146147 # One entry per manual page. List of tuples
147148 # (source start file, name, description, authors, manual section).
148149 man_pages = [
149150 (master_doc, project, '%s documentation' % project, [author], 1),
150 ('modules', project, '%s module documentation' % project, [author], 5)
151
152 ('modules', project, '%s module documentation' % project, [author], 3),
153
154 ('config_files', project, '%s configuration file documentation' % project,
155 [author], 5)
151156 ]
152157
153158
0 .. eclecti_deploy documentation master file, created by
1 sphinx-quickstart on Thu May 2 01:04:43 2019.
2 You can adapt this file completely to your liking, but it should at least
3 contain the root `toctree` directive.
4
5 Welcome to eclecti_deploy's documentation!
6 ==========================================
7
8 .. toctree::
9 :maxdepth: 2
10 :caption: Contents:
11
12
13 ===========
14 DESCRIPTION
15 ===========
16
17
18 - Configuration files use :term:`YAML` for easy syntax. See their docs for more
19 reference on syntax.
20
21 - Configuration files can always be initialized using "``eclecti_deploy config init``"
22
23 - Configuration files specify required lines inline using "``# REQUIRED``" comments
24
25 - Configuration files are conventionally placed in the root folder of a project
26 (although this behaviour is not forced)
27
28 -------------
29 ``Host`` Data
30 -------------
31
32 Defines the following data:
33
34 - The remote username
35
36 - The remote host
37
38 - The remote path to transfer project files to
39
40 .. note:: The remote username, host and remote path are all required
41
42 .. warning:: The software does not provide a way to store passwords, nor does
43 it allow the user to enter an ssh password. See the docs for
44 ``ssh-copy-id`` for more on how to set up ssh key login.
45
46 ----------------
47 ``Project`` Data
48 ----------------
49
50 Defines the following data:
51
52 - The path to the local project
53
54 - The path to the local requirements file (for python)
55
56 .. note:: The path defaults to "``./``" which is likely useful if the
57 configuration file is placed conventionally within the project
58
59 .. note:: The path to the local requirement file defaults to ``requiremetns.txt``
60 which is likely useful if the configuration file is placed in
61 conventionally within the project
62
63
64 -------------------------
65 Deploy & Compile Commands
66 -------------------------
67
68 .. todo:: to be implemented!
69
70 To be used for custom pre and post deployment commands
1111
1212
1313
14 Indices and tables
15 ==================
14 ========
15 SYNOPSES
16 ========
1617
17 * :ref:`genindex`
18 * :ref:`modindex`
19 * :ref:`search`
18 Usage: **eclecti_deploy** *[OPTIONS] COMMAND [ARGS]*...
19
20 Provides custom deployment utilities for Eclectick Media Solutions flask
21 sites
22
23 Options:
24 --help Show this message and exit.
25
26 Commands:
27 config .deploy file utilities
28 remote Interact with remote system
29
30 ===========
31 DESCRIPTION
32 ===========
33
34 Provides utilities for deploying Flask sites developed by :term:`Eclectic Media
35 Solutions`
36
37 Those utilities include, but are not limited to:
38
39 - File transfer utilities (using ``rsync``)
40
41 - Remote host configuration, including nginx/wsgi & python/gunicorn/flask stacks
42
43 - Access to specific utilities on remote hosts
44
45 The software aims to provide standardization throughout :term:`Eclectic Media
46 Solutions` maintained websites that use the :term:`Flask` micro framework.
47
48 -------------------
49 Configuration Files
50 -------------------
51
52 The software uses configuration files to determine what is project is where, and
53 where to send it to. These configuration files can be placed anywhere, but are
54 usually placed in the root directory of a project (by convention).
55
56 To initialize a deploy configuration file, run "``eclecti_deploy config init``"
57 to copy a new config file to "``./.deploy.yml``".
58
59 Once you have completed modifying the configuration file, you can run
60 "``eclecti_deploy config verify``" to confirm the configuration file is OK.
61
62 .. warning:: All utilities require a configuration file, so before you can use
63 them, you must create a configuration file.
64
65 For more on the configuration file format, see eclecti_deploy(5) for more.
66
67
68 =======
69 Options
70 =======
71
72 The software provides many utilities, each callable from a subcommand. Where:
73 ::
74
75 eclecti_deploy remote
76
77 Targets remote utilities, and where:
78 ::
79
80 eclecti_deploy remote transfer
81
82 Targets remote transfer utilities.
83
84 **For a full list of commands, see the documentation for each with "eclecti_deploy COMMAND --help"**
85
86 ===========
87 Exit Status
88 ===========
89
90 **0** - Exited OK
91 **1** - Runtime Failure
92
93 ========
94 GLOSSARY
95 ========
96
97 .. glossary::
98
99 .deploy.yml
100 Default configuration file to get valid host and project details from the user.
101
102 Eclectic Media Solutions
103 The organization behind the software. Visit http://eclecticmedia.hopto.org
104 for more.
105
106 Flask
107 A python web micro framework. Visit http://flask.pocoo.org/ for more.
108
109 YAML
110 Yet Another Markup Language, visit https://yaml.org/ for more.
99 :maxdepth: 2
1010 :caption: Contents:
1111
12 ===========
13 DESCRIPTION
14 ===========
15
16 Defines the building blocks of commands, for further extension and rolling your
17 own.
18
19 ============================
20 BASE CONFIGURATION FUNCTIONS
21 ============================
22
23 .. automodule:: eclecti_deploy
24 :members:
1225
1326
14 Indices and tables
15 ==================
27 ==========================================
28 FAB CONFIGURATION AND CONNECTION FUNCTIONS
29 ==========================================
1630
17 * :ref:`genindex`
18 * :ref:`modindex`
19 * :ref:`search`
31 .. automodule:: eclecti_deploy.fab
32 :members:
33 :private-members: