Documentation

[Ede123]

The project needs proper documentation.

Current consensus is that

• using Sphinx to create the documentation and
• publishing the result on Read the Docs

would be the preferred way to approach this.

[nthykier]

I think it will be easier to contribute to fixing this issue if we can put some high level description of what we want from the documentation. E.g a basic document structure (from a bunch of headlines and expected names of subsections).

Here is a initial high level draft in markdown to get the ball rolling:

# What is scour

Something about the scour project and what the tool does (and does not do) 

# Installing scour

The basic pip invocation

# Running scour

Basic examples of running scour including some options.  Include examples like

  * No options at all
  * Remove all white space/indentation
  * Scour as much as possible to produce minimal images

## All command line options

The full list of command line options, what they do.

## Known caveats

We know that scour is not perfect (e.g. inline CSS, sometimes you have protect ids etc.).  This section will cover our known issues and how to work around them (where possible).

## Performance notes

What we expect from performance; the fact that python3.6 is significantly faster than python2, very large images may require a significant amount of memory, etc.

# Python API

Pending a solution #119

[JoKalliauer]

@nthykier

Running scour

I wrote a Documentation about "Running scour": https://github.com/scour-project/scour/wiki/Documentation-(first-draft)

Installing scour

"Installing scour" should be explained here: https://github.com/scour-project/scour#installation

Missing: Explantation of:

python -m pip install --upgrade pip
pip3 install --upgrade https://github.com/codedread/scour/archive/master.zip

[sharethewisdom]

I want to let my package manager install html docs to /usr/share/doc/. Could this be made downloadable please?

In order for dev packages to be able to build and install docs to /usr/share/doc/ one should probably separate a sphinx build rule from a publish rule in the makefile.

[JoKalliauer]

I find https://github.com/scour-project/scour/wiki/Documentation helpful for finding duplicates of bugreports, because if you know the option that causes the issue, you see the bugs related to this option.

Maybe this should be split:
-one list with an explanation of the features
-one list of bugreports, splitted with the according options, to avoid duplicates.