From ccae7b2022655677a0c4f098358216f5214f84bb Mon Sep 17 00:00:00 2001 From: Oleg Butuzov Date: Sun, 1 Dec 2019 18:27:18 +0200 Subject: [PATCH] docs(all): Pre release docs * removed empty pages * build pipeline changed * ci pipeline changed * added sphinx docs --- .travis.yml | 5 +- Makefile | 9 ++-- docs/_static/.git_tracking | 1 + docs/conf.py | 9 ++-- docs/continuous-integration/readme.md | 3 -- docs/continuous-integration/travis-ci.md | 59 ++++++++++++++++++++++++ docs/documenting-code.md | 13 ------ docs/readme.md | 14 +----- docs/static-site-generators.md | 37 +++++++++++++++ 9 files changed, 110 insertions(+), 40 deletions(-) create mode 100644 docs/_static/.git_tracking create mode 100644 docs/continuous-integration/travis-ci.md delete mode 100644 docs/documenting-code.md create mode 100644 docs/static-site-generators.md diff --git a/.travis.yml b/.travis.yml index 8f5cc3a..cf6c9a7 100644 --- a/.travis.yml +++ b/.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 diff --git a/Makefile b/Makefile index 709154f..059b020 100644 --- a/Makefile +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/_static/.git_tracking b/docs/_static/.git_tracking new file mode 100644 index 0000000..25c19ea --- /dev/null +++ b/docs/_static/.git_tracking @@ -0,0 +1 @@ +this file for empty directory tracking diff --git a/docs/conf.py b/docs/conf.py index ed4c3f7..04ff2ab 100644 --- a/docs/conf.py +++ b/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', diff --git a/docs/continuous-integration/readme.md b/docs/continuous-integration/readme.md index 9ba048c..9e67ebf 100644 --- a/docs/continuous-integration/readme.md +++ b/docs/continuous-integration/readme.md @@ -16,8 +16,5 @@ If tool you using to create documentation has support for links checking, please

Continues Integration Providers

-* [Azure Pipelines](azure-pipelines.md) -* [GitHub Actions](github-actions.md) -* [Jenkins](jenkins.md) * [tox](tox.md) * [Travis CI](travis-ci.md) diff --git a/docs/continuous-integration/travis-ci.md b/docs/continuous-integration/travis-ci.md new file mode 100644 index 0000000..feecf13 --- /dev/null +++ b/docs/continuous-integration/travis-ci.md @@ -0,0 +1,59 @@ +# Travis CI + +Example integration can take next steps and looks like code below: + +

Handling Static Files

+ +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. + +

Serving Files

+ +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. diff --git a/docs/documenting-code.md b/docs/documenting-code.md deleted file mode 100644 index d6bb5cf..0000000 --- a/docs/documenting-code.md +++ /dev/null @@ -1,13 +0,0 @@ -# Documenting Code - -List of tools that can use useful for creating documentation. - - - - Title | Supports Links Checking | Supports Serving Documentation | Language ----------------------------------------|-------------------------|--------------------------------|---------- - [Hugo](https://gohugo.io/) | No | Yes ( w Live Reloads) | Go - [Sphinx](https://www.sphinx-doc.org/) | Yes | No | Python - [MkDocs](https://www.mkdocs.org/) | Yes | Yes ( w Live Reloads) | Python - - diff --git a/docs/readme.md b/docs/readme.md index 0e33708..14c0d9e 100644 --- a/docs/readme.md +++ b/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) diff --git a/docs/static-site-generators.md b/docs/static-site-generators.md new file mode 100644 index 0000000..324e40a --- /dev/null +++ b/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 +```