Commit d30d192b authored by Marvin Scholz's avatar Marvin Scholz

Add mkdocs to repo and generate them with automake

parent b7087c38
......@@ -141,6 +141,21 @@ XIPH_PATH_OPENSSL([
[ AC_MSG_NOTICE([SSL disabled!])
])
dnl Documentation
AC_PATH_PROG([MKDOCS], [mkdocs], [no])
AS_IF([test "$MKDOCS" = "no"], [
AC_MSG_WARN([mkdocs not found - generating docs will be disabled])
])
AM_CONDITIONAL([HAVE_MKDOCS], [test ! "$MKDOCS" = "no"])
AM_COND_IF([HAVE_MKDOCS], [
AC_CONFIG_FILES([doc/mkdocs.yml])
])
dnl Make substitutions
AC_SUBST(XIPH_CPPFLAGS)
......@@ -161,8 +176,6 @@ AC_SUBST(KATE_LIBS)
AC_OUTPUT([Makefile conf/Makefile src/Makefile src/common/avl/Makefile
src/common/httpp/Makefile src/common/thread/Makefile src/common/log/Makefile
src/common/net/Makefile src/common/timing/Makefile doc/Makefile doc/img/Makefile
doc/assets/Makefile doc/assets/css/Makefile doc/assets/font/Makefile
doc/assets/img/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile
src/common/net/Makefile src/common/timing/Makefile doc/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile
web/assets/font/Makefile admin/Makefile admin/includes/Makefile win32/Makefile
examples/Makefile])
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
SUBDIRS = assets img
EXTRA_DIST = \
mkdocs.yml \
docs/img/icecast_shema.svg \
docs/admin_interface.md \
docs/auth.md \
docs/basic_setup.md \
docs/config_file.md \
docs/index.md \
docs/introduction.md \
docs/relaying.md \
docs/server_stats.md \
docs/win32.md \
docs/yp.md
docdir = $(datadir)/doc/icecast
doc_DATA = admin-interface.html auth.html changes.html faq.html \
introduction.html relaying.html win32.html basic-setup.html \
config-file.html glossary.html index.html server-stats.html yp.html
EXTRA_DIST = $(doc_DATA)
# Documentation generation
if HAVE_MKDOCS
# Directory where the docs will end up
directory = $(top_srcdir)/doc/icecast/
EXTRA_DIST += $(directory)
mkdocs.stamp:
cd "$(top_srcdir)/doc" && $(MKDOCS) build -d "$(directory)"
echo STAMP > mkdocs.stamp
CLEANFILES = mkdocs.stamp
install-data-local:
echo FIXMEFIXMEFIXME
exit
$(INSTALL) -d "$(directory)" "$(docdir)"
uninstall-local:
( cd "$(directory)"; find . -type f -print0) | (cd "$(docdir)"; xargs -0 rm )
all-local: mkdocs.stamp
clean-local:
rm -rf "$(directory)"
endif
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Admin Interface</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Admin Interface</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>This section contains information about the admin interface of icecast. Through this interface the user can manipulate many server features. From it you can gather statistics, move listeners from mountpoint to mountpoint, disconnect connected sources, disconnect connected listeners, and many other activities. Each function is enumerated here as well as an example usage of the function.</p>
<p>Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the <code>&lt;admin-username&gt;</code> and <code>&lt;admin-password&gt;</code> specified in the icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. It is also important to note that in all the examples 192.168.1.10 is used as the example host and 8000 is used as the example port for the icecast server.</p>
</div>
<div class="article">
<h3 id="admin-functions-mount-specific">Admin Functions (mount specific)</h3>
<p>All these admin functions are mount specific in that they only apply to a particular mountpoint
(as opposed to applying to the entire server). Each of these functions requires a mountpoint to
be specified as input.</p>
<h4 id="metadata-update">Metadata Update</h4>
<p>This function provides the ability for either a source client or any external program to update
the metadata information for a particular mountpoint.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/metadata?mount=/mystream&amp;mode=updinfo&amp;song=ACDC+Back+In+Black</code></p>
<h4 id="fallback-update">Fallback Update</h4>
<p>This function provides the ability for either a source client or any external program to update the
“fallback mountpoint” for a particular mountpoint. Fallback mounts are those that are used in the even
of a source client disconnection. If a source client disconnects for some reason that all currently
connected clients are sent immediately to the fallback mountpoint.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&amp;fallback=/myfallback.ogg</code></p>
<h4 id="list-clients">List Clients</h4>
<p>This function lists all the clients currently connected to a specific mountpoint. The results are sent
back in XML form.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg</code></p>
<h4 id="move-clients-listeners">Move Clients (Listeners)</h4>
<p>This function provides the ability to migrate currently connected listeners from one mountpoint to another.
This function requires 2 mountpoints to be passed in: mount (the <em>from</em> mountpoint) and destination
(the <em>to</em> mountpoint). After processing this function all currently connected listeners on mount will
be connected to destination. Note that the destination mountpoint must exist and have a sounce client
already feeding it a stream.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&amp;destination=/mynewstream.ogg</code></p>
<h4 id="kill-client-listener">Kill Client (Listener)</h4>
<p>This function provides the ability to disconnect a specific listener of a currently connected mountpoint.
Listeners are identified by a unique id that can be retrieved by via the “List Clients” admin function.
This id must be passed in to the request via the variable <code>id</code>. After processing this request, the listener will no longer be
connected to the mountpoint.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&amp;id=21</code></p>
<h4 id="kill-source">Kill Source</h4>
<p>This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint
to be disconnected is specified via the variable <code>mount</code>.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg</code></p>
</div>
<div class="article">
<h3 id="admin-functions-general">Admin Functions (general)</h3>
<h4 id="stats">Stats</h4>
<p>The stats function provides the ability to query the internal statistics kept by the Icecast server.
Almost all information about the internal workings of the server such as the mountpoints connected,
how many client requests have been served, how many listeners for each mountpoint, etc, are available
via this admin function.<br />
Note that this admin function can also be invoked via the http://server:port/admin/stats.xml syntax,
however this syntax should not be used and will eventually become deprecated!</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/stats</code></p>
<h4 id="list-mounts">List Mounts</h4>
<p>The list mounts function provides the ability to view all the currently connected mountpoints.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/listmounts</code></p>
</div>
<div class="article">
<h3 id="web-based-admin-interface">Web-Based Admin Interface</h3>
<p>As an alternative to manually invoking these URLs, a web-based admin interface was developed. This
interface provides the same functions that were identified and described above but presents them in
a little nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the
<code>admin</code> directory and comes ready to use. All the user needs to do is set the path to this directory
in the config file via the <code>&lt;adminroot&gt;</code> config variable.<br />
The web-based admin interface is a series of XSLT files which are used to display all the XML obtained
via the URL admin interface. This can be changed and modified to suit the user’s need. Knowledge of
XSLT and transformations from XML to HTML are required in order to make changes to these scripts. </p>
<p>The main URL for the Web-Based Admin Interface is:<br />
<code>http://192.168.1.10:8000/admin/stats.xsl</code> </p>
<p>From this URL all of the other admin functions can be exercised.
<strong>Modification of existing XSLT transforms in <code>/admin</code> is allowed, but new files cannot be created here</strong>.
Creation of new XSLT transforms as well as modification of existing transforms is allowed in <code>/web</code>.
These work using the document returned by <code>/admin/stats.xml</code>.<br />
To see the XML document that is applied to each admin XSLT, just remove the <code>.xsl</code> in your request
(i.e. <code>/admin/listclients</code>). You can then code your XSLT transform accordingly.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
SUBDIRS = css font img
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
otherdocdir = $(docdir)/assets/css
otherdoc_DATA = style.css
EXTRA_DIST = $(otherdoc_DATA)
@charset "UTF-8";
/* Typeface */
@font-face {
font-family: 'FiraSans';
font-style: normal;
font-weight: normal;
src: url('../font/FiraSans-Regular.eot');
src: url('../font/FiraSans-Regular.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-Regular.woff') format('woff');
}
@font-face {
font-family: 'FiraSans';
font-style: italic;
font-weight: normal;
src: url('../font/FiraSans-Italic.eot');
src: url('../font/FiraSans-Italic.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-Italic.woff') format('woff');
}
@font-face {
font-family: 'FiraSans';
font-style: normal;
font-weight: bold;
src: url('fonts/FiraSans/FiraSans-Bold.eot');
src: url('../font/FiraSans-Bold.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-Bold.woff') format('woff');
}
@font-face {
font-family: 'FiraSans';
font-style: italic;
font-weight: bold;
src: url('../font/FiraSans-BoldItalic.eot');
src: url('../font/FiraSans-BoldItalic.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-BoldItalic.woff') format('woff');
}
@font-face {
font-family: 'FiraMono';
font-style: normal;
font-weight: normal;
src: url('../font/FiraMono-Regular.eot');
src: url('../font/FiraMono-Regular.eot?#iefix') format('embedded-opentype'), url('../font/FiraMono-Regular.woff') format('woff');
}
@font-face {
font-family: 'FiraMono';
font-style: normal;
font-weight: bold;
src: url('../font/FiraMono-Bold.eot');
src: url('../font/FiraMono-Bold.eot?#iefix') format('embedded-opentype'), url('../font/FiraMono-Bold.woff') format('woff');
}
/* General */
*,
*:before,
*:after {
font-family: 'FiraSans', sans-serif;
line-height: 1;
margin: 0;
padding: 0;
border: 0;
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
text-rendering: optimizelegibility;
}
::selection {
background: #9AABB5;
color: #001826;
text-shadow: none;
}
::-moz-selection {
background: #9AABB5;
color: #001826;
text-shadow: none;
}
.hidden {
clip: rect(0 0 0 0);
overflow: hidden;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
position: absolute;
border: 0;
}
/* Typography */
h1,
h2,
h3,
h4 {
line-height: 1.25;
}
h1 {
font-size: 2em;
font-weight: normal;
}
h2 {
font-size: 2em;
}
h3 {
font-size: 1.5em;
}
h4 {
font-size: 1.25em;
}
h5 {
font-size: 1em;
text-transform: uppercase;
}
p,
li,
blockquote,
dl > *,
aside {
line-height: 1.6;
-webkit-hyphens: auto;
-moz-hyphens: auto;
hyphens: auto;
}
blockquote {
font-style: italic;
}
q {
quotes:"\201E" "\201C";
}
code,
pre {
background-color: #000E17;
color: #9AABB5;
font-family: 'FiraMono', monospace;
line-height: 1.6;
}
code {
word-break: break-all;
}
pre {
white-space: pre-wrap;
padding: 1em;
}
code span,
pre span {
font-family: 'FiraMono', monospace;
}
/* Chrome fix */
@media screen and (-webkit-min-device-pixel-ratio: 0) {
pre {
word-break: break-all;
}
}
hr {
padding-bottom: 1em;
margin-top: 2em;
clear: both;
border: 0;
border-top: 2px solid #29495C;
}
dt {
font-weight: bold;
}
dd {
margin-left: 1em;
}
/* Tables */
table {
width: 100%;
border-collapse: collapse;
border-spacing: 0;
}
th, td {
text-align: left;
line-height: 1.6;
padding: .5em;
vertical-align: top;
}
th {
background-color: #000E17;
text-shadow: 1px 1px 0 rgba(0,0,0,0.5);
}
td {
border: 2px solid #000E17;
}
td a {
word-break: break-all;
}
/* Inputs */
::-webkit-input-placeholder {
color: #9AABB5;
}
:-moz-placeholder {
color: #9AABB5;
opacity: 1;
}
::-moz-placeholder {
color: #9AABB5;
opacity: 1;
}
:-ms-input-placeholder {
color: #9AABB5;
}
input::-ms-clear {
display: none;
}
input:not([type="submit"]), textarea {
font: 1em 'FiraMono', monospace
}
input, textarea {
width: 50%;
}
input[type='text'],
input[type='email'],
input[type='password'],
input[type='url'] {
background-color: #000E17;
color: #9AABB5;
display: block;
padding: 1em;
}
input[type='submit'] {
background-color: #001826;
font-size: 1em;
color: #FFFFFF;
display: block;
padding: 1em;
border: 2px solid #29495C;
}
input[type='submit']:hover {
background-color: #29495C;
cursor: pointer;
}
input[type='checkbox'] + label {
display: inline-block !important;
margin: 10px 0 0 10px;
}
form > *:not(:last-child) {
margin-bottom: 1em;
}
/* Links */
a:link,
a:visited {
color: #9AABB5;
text-decoration: underline;
}
a:hover,
a:focus,
a:active {
color: #29495C;
}
a.permalink:link,
a.permalink:visited {
text-decoration: none;
display: none;
}
a.permalink:hover,
*:hover > a.permalink {
display: inline-block;
padding-left: .25em;
}
/* Body */
body {
background-color: #CAD5DB;
color: #001826;
}
body > * {
margin: 0 auto;
}
body > *:not(:first-child) {
width: 75%;
margin: 0 auto;
}
/* Header */
header,
.header {
background-color: #001826;
position: relative;
margin-bottom: 2em;
box-shadow: 0 0 2em rgba(0,0,0,0.5) inset;
}
#xiphbar {
background-color: #666666;
height: 2.25em;
box-shadow: 0 .25em .25em rgba(0,0,0,.5);
}
#xiphbar > div {
width: 75%;
margin: 0 auto;
position: relative;
}
#xiphbar > div > * {
position: absolute;
top: 0.5em;
}
#xiphbar > div > a {
display: block;
}
#xiphbar img {
width: auto;
height: 1.25em;
}
#xiphbar > div > ul {
right: 0;
display: -webkit-box;
display: -moz-box;
display: -ms-flexbox;
display: flex;
flex-direction: row;
list-style: none;
}
#xiphbar li {
font-size: 14px;
margin: 0;
}
#xiphbar li:not(:first-child) {
margin-left: 1em;
}
#xiphbar a:link,
#xiphbar a:visited {
color: #ffcc66;
text-decoration: none;
text-transform: uppercase;
border: none;
}
#xiphbar a:hover,
#xiphbar a:focus {
color: #ffe6b3;
}
#xiphbar a:active {
color: #FFFFFF;
}
header h1,
.header h1 {
color: #29495C;
text-shadow: 1px 1px 0 rgba(0,0,0,0.5);
width: 75%;
padding: 2em 0;
margin: 0 auto;
}
header h1 a:link,
header h1 a:visited,
.header h1 a:link,
.header h1 a:visited {
color: #FFFFFF;
font-weight: bold;
text-decoration: none;
border-bottom: none;
}
header h1 a:hover,
header h1 a:focus,
.header h1 a:hover,
.header h1 a:focus {
text-decoration: underline;
}
header h1 a:active,
.header h1 a:active {
color: #29495C;
}
/* Navigation */
nav,
.nav {
margin: 0 auto;
border-top: 2px solid #29495C;
border-bottom: 2px solid #29495C;
}
nav label,
.nav label,
#toggle-nav {
display: none;
}
nav label:before,
.nav label:before {
content: '\2261';
color: #29495C;
font-size: 4em;
text-shadow: 1px 1px 0 rgba(0,0,0,0.5);
position: absolute;
top: 0.9em;
right: 0.5em;
}
nav label.nobar:before,
.nav label.nobar:before {
top: 0.4em;
}
nav label:hover,
nav label:hover:before,
.nav label:hover,
.nav label:hover:before {
color: #FFFFFF;
cursor: pointer;
}
#toggle-nav:checked + ul {
display: block;
}
nav ul,
.nav ul {
margin: 0 auto;
}
nav ul:before,
nav ul:after,
.nav ul:before,
.nav ul:after {
display: table;
content: ' ';
clear: both;
}
nav li,
.nav li {
display: table-cell;
width: 1%;
}
nav li.on a,
.nav li.on a {
font-weight: bold;
}
nav a:link,
nav a:visited,
.nav a:link,
.nav a:visited {
background-color: #001826;
color: #FFFFFF
;letter-spacing: 0.1em;
white-space: nowrap;
text-transform: uppercase;
text-decoration: none;
text-align: center;
padding: 1em;
display: block;
border-right: 2px solid #29495C;
border-bottom: none;
position: relative;
}
nav li:last-child a,
.nav li:last-child a {
border-right: none;
}
nav a:after,
.nav a:after {
content: '\0020';
color: transparent;
width: 100%;
height: 100%;
position: absolute;
top: 0;
left: 0;
opacity: 0;
-ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=0)";
filter: alpha(opacity=0);
border: 5px solid #29495C;
}
nav a:focus,
.nav a:focus {
color: #29495C;
}
nav a:hover:after,
nav a:active:after,
nav a:focus:after,
.nav a:hover:after,
.nav a:active:after,
.nav a:focus:after {
opacity: 1;
-ms-filter: none;
filter: none;
}
/* Content */
section h2,
.section h2 {
margin-bottom: 1em;
}
section > a:link,
section > a:visited,
.section > a:link,
.section > a:visited {
color: #29495C;
}
section > a:hover,
.section > a:hover {
text-decoration: none;