docs(all): Pre release docs

* removed empty pages
* build pipeline changed
* ci pipeline changed
* added sphinx docs

.travis.yml

@@ -8,13 +8,11 @@ matrix:
   allow_failures:
   - env: FAILURES=ALLOWED
 
-
 install:
 - make requirements
 
 script: skip
 
-
 jobs:
   include:
     # OK: Tests --------------------------------------------------
@@ -37,7 +35,6 @@ jobs:
       name: "Tests (Python 3.5)"
       python: 3.5
 
-
     # OK: Linters ------------------------------------------------
     - stage: lints
       name: "Running Linters"
@@ -51,7 +48,7 @@ jobs:
       script:
       - make install
       - make gen-docs
-      - deadlinks internal --root=build/sphinx/html --no-progress --no-colors --fiff
+      - make check-docs
 
     # OK: CodeCoverage -------------------------------------------
     - stage: codecov

Makefile

@@ -71,12 +71,15 @@ browse:
 	open http://localhost:5678
 
 documentation:
-	ghp -root=build/sphinx/html -port=5678
+	ghp -root=build/html -port=5678
 
 gen-docs:
-	python3 setup.py build_sphinx -c docs
+	sphinx-build docs build/html -qW --keep-going
 
-docs: gen-docs browse  documentation
+check-docs:
+	deadlinks internal --root=build/html --no-progress --no-colors --fiff
+
+docs: gen-docs browse check-docs documentation
 
 # ~~~ Brew ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/_static/.git_tracking

@@ -0,0 +1 @@
+this file for empty directory tracking

docs/conf.py

@@ -11,9 +11,9 @@
 # templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-source_suffix = [
-    '.md',
-]
+source_suffix = {
+    '.md': 'markdown',
+}
 
 # The master toctree document.
 master_doc = 'index'
@@ -107,7 +107,8 @@ def visit_code(self, mdnode):
 
 def setup(app):
     from recommonmark.transform import AutoStructify
-    app.add_source_parser('.md', MyCommonMarkParser)
+    app.add_source_suffix('.md', 'markdown')
+    app.add_source_parser(MyCommonMarkParser)
 
     app.add_config_value(
         'recommonmark_config',

docs/continuous-integration/readme.md

@@ -16,8 +16,5 @@ If tool you using to create documentation has support for links checking, please
 
 <h2>Continues Integration Providers</h2>
 
-* [Azure Pipelines](azure-pipelines.md)
-* [GitHub Actions](github-actions.md)
-* [Jenkins](jenkins.md)
 * [tox](tox.md)
 * [Travis CI](travis-ci.md)

docs/continuous-integration/travis-ci.md

@@ -0,0 +1,59 @@
+# Travis CI
+
+Example integration can take next steps and looks like code below:
+
+<h3>Handling Static Files</h3>
+
+If tool, you using for static site generation doesn't support serving files, you can pass this task to deadlinks using `internal` keyword and `--root` option.
+
+```yaml
+
+language: python
+python: 3.8
+
+# Install step will install dependencies (sphinx) and deadlinks
+install:
+- pip install -r requirements.txt
+- pip install deadlinks
+
+# Build step will create artifacts (in html directory) and deadlinks
+# will check directory  `html` and fail if failed urls found.
+script:
+- sphinx-build docs html -qW --keep-going
+- deadlinks internal -R html --no-progress --no-colors --fiff
+
+# You can deploy artifacts to github pages if pipeline passes.
+deploy:
+  provider: pages
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN
+  local_dir: html
+  on:
+    branch: master
+```
+
+Read more about `sphinx` at [Static Site Generators](../static-site-generators#sphinx) page.
+
+<h3>Serving Files</h3>
+
+If your tool can serve html files, just run serving in background
+
+```yaml
+language: python
+python: 3.8
+
+# Install step will install dependencies (mkdocs) and deadlinks
+install:
+- pip install -r requirements.txt
+- pip install deadlinks
+
+# We running build for static files first, and then running it again in the `serve`
+# mode, `deadlinks` is checking web address on which documentation served.
+script:
+- mkdocs build --strict
+- mkdocs serve --dirtyreload --dev-addr 127.0.0.1:8080 &
+- deadlinks http://127.0.0.1:8080 -n10 -r3  --no-progress --no-colors --fiff
+
+```
+
+Read more about `mkdocs` at [Static Site Generators](../static-site-generators#mkdocs) page.

docs/readme.md

@@ -5,16 +5,4 @@
 * [Installation](install.md)
 * [Usage Examples](usage-examples/index.md)
 * [Continuous Integration](continuous-integration/index.md)
-
-
-
-
-
-
-
-
-
-
-
-
-
+* [Static Site Generators](static-site-generators.md)

docs/static-site-generators.md

@@ -0,0 +1,37 @@
+# Static Site Generators
+
+There are [number of options](https://www.staticgen.com/) you can use for static website or documentation generation, and we honestly can't recommend any particular. However it's important to understand that `deadlinks` itself designated to eliminate just one issue with documentation - dead or broken links, static site generator you using, can have additional features that will improve your CI process. It's nice to know `what` tools can do `what` and integrate their features into CI.
+
+Static site generator can:
+* Show information about missing links or not included files.
+* Describe markup errors found in source files
+* Check for the issues with external or internal links too.
+
+This is incomplete list of known CI features you can integrate in your pipeline.
+
+
+## [Sphinx](https://www.sphinx-doc.org/)
+
+Sphinx itself, doesn't support files serving, so we will always rebuild files before testing, however it checks included, missing links, and generate corresponding warnings. You also can use `sphinx` via `setup.py`
+
+```bash
+#  -q will limit output only to warnings
+#  -W will turn warnings into errors
+#  --keep-going will show all found errors, not just first one.
+sphinx-build docs html -qW --keep-going
+
+# same effect if used via setup.py
+python3 setup.py build_sphinx -c docs --build-dir build -qW --keep-going
+```
+
+## [MkDocs](https://www.mkdocs.org/)
+
+MkDocs is quite nice and configurable static docs generator, which can serve files and exit on warnings (`--strict` option).
+
+```bash
+# Serve files at 127.0.0.1:8080
+mkdocs serve --strict --dirtyreload --dev-addr 127.0.0.1:8080
+
+# Just build files
+mkdocs build --strict
+```