README.md
1# Dosage
2
3[](https://travis-ci.org/webcomics/dosage)
4[](https://codeclimate.com/github/webcomics/dosage)
5[](https://codecov.io/gh/webcomics/dosage)
6[]()
7
8Dosage is designed to keep a local copy of specific webcomics and other
9picture-based content such as Picture of the Day sites. With the dosage
10commandline script you can get the latest strip of a webcomic, or catch-up to
11the last strip downloaded, or download a strip for a particular date/index (if
12the webcomic's site layout allows this).
13
14Multiple webcomics can be downloaded in parallel, making the update of comic
15strips faster.
16
17## Notice
18
19This software is in no way intended to publically "broadcast" comic strips, it
20is purely for personal use. Please be aware that by making downloaded strips
21publically available (without the explicit permission of the author) you may be
22infringing upon various copyrights.
23
24Additionally, Dosage respects the robots.txt exclusion protocol. This makes
25sure no content is accessed in an automatic way without consent by the
26publishers.
27
28In any case, you should support the authors of the comics you are downloading,
29either by buying some of their products or even donating them some money since
30they provide the comics you like and read.
31
32If you are a publisher of comics and want Dosage to access your files,
33add the following entry to your robots.txt file:
34
35 User-agent: Dosage
36 Allow: *
37
38## Usage
39
40List available comics (ca. 3000 at the moment):
41
42 $ dosage --list
43
44Get the latest comic of for example CalvinAndHobbes and save it in the "Comics"
45directory:
46
47 $ dosage CalvinAndHobbes
48
49If you already have downloaded several comics and want to get the latest strip
50of all of them:
51
52 $ dosage @
53
54
55To help others find good comics, you can vote for your favourite ones:
56
57 $ dosage --vote @
58
59For advanced options and features execute `dosage --help`.
60
61### Adult content
62
63Some comics contain adult content and require age confirmation. These comics
64can only be downloaded by using the `--adult` option, which confirms that you
65are old enough to view them.
66
67## Installation
68
69### Dependencies
70
71Since dosage is written in [Python](http://www.python.org/), a Python
72installation is required: for Python 2.x at least 2.7.0, for Python 3.x at
73least Python 3.5. Dosage requires some Python modules from PyPI, so
74installation with `pip` is recommended.
75
76### Using the Windows binary
77
78Windows users can download a complete binary (including Python) from the
79[release page].
80
81[release page]: https://github.com/webcomics/dosage/releases/latest
82
83### Install with pipx
84
85The simplest way to install and upgrade dosage is with [pipx]. To install the
86newest stable version with all optional features use:
87
88 pipx install --spec dosage[css,bash] dosage
89
90To install the newest development version, use:
91
92 pipx install --spec "dosage[css,bash] @ git+https://github.com/webcomics/dosage.git" dosage
93
94To upgrade such installations, just run:
95
96 pipx upgrade dosage
97
98### Installation for development
99
100If you want to run dosage directly from the source code, you should install
101it in "[editable]" mode, preferable in a [virtual environment]:
102
103 pip install -e .[css,bash]
104
105You can invoke Dosage directly from the source code as `./dosage`, but this
106mode of operation is discouraged, since dependencies might be missing.
107
108[pipx]: https://github.com/pipxproject/pipx
109[editable]: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
110[virtual environment]: https://docs.python.org/3/library/venv.html
111
112## Reporting Bugs
113
114You can report bugs, patches or requests at the [GitHub issue
115tracker](https://github.com/webcomics/dosage/issues) - Dosage currently
116supports a large number of comics and that number grows on a regular basis. If
117you feel that there are comics that Dosage does not currently support, but
118should support, please feel free to request them.
119
120## Extending Dosage
121
122In order to add a new webcomic, a new module class has to be created in one of
123the *.py files in the `dosagelib/plugins` subdirectory. Look at the
124[documentation for adding modules](doc/adding_new_comics.md) and at
125existing module classes for examples.
126
127### Test suite status
128
129Dosage has extensive unit tests to ensure the code quality.
130[Travis-CI](https://travis-ci.org/) is used for continuous build and test
131integration. See the badges at the top of this page for the current status.
132
){kind=link}
){kind=link}
){kind=link}
){kind=link}