From 1c00b4812edb439f47938d074b9c4f73b2cc0ad3 Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 31 Aug 2020 00:59:22 +0200 Subject: ci: use buildthedocs/btd to build and publish the docs to GHP --- .btd.yml | 9 +++++++++ .github/CONTRIBUTING.md | 6 +++--- .github/PULL_REQUEST_TEMPLATE.md | 6 +++--- .github/workflows/doc.yml | 22 +++++++++++++++++++--- README.md | 16 ++++++++-------- doc/_static/logo.png | Bin 0 -> 3963 bytes doc/_static/theme_overrides.css | 12 ------------ doc/conf.py | 31 +++++++++++++++++-------------- doc/index.rst | 33 ++++++++++++++++++++++++++------- doc/requirements.txt | 3 +-- doc/shields.json | 32 ++++---------------------------- logo.png | Bin 3963 -> 0 bytes 12 files changed, 90 insertions(+), 80 deletions(-) create mode 100644 .btd.yml create mode 100644 doc/_static/logo.png delete mode 100644 logo.png diff --git a/.btd.yml b/.btd.yml new file mode 100644 index 000000000..7fde40f6a --- /dev/null +++ b/.btd.yml @@ -0,0 +1,9 @@ +input: doc +output: _build +requirements: requirements.txt +target: gh-pages +formats: [ html, pdf, man ] +images: + base: ghdl/doc + latex: btdi/latex +theme: https://codeload.github.com/buildthedocs/sphinx.theme/tar.gz/v0 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9e881844a..3503a587b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,8 +2,8 @@ GHDL is a free and open source software brought to you with :heart: by [@tgingold](https://github.com/tgingold) and [contributors](https://github.com/ghdl/ghdl/graphs/contributors). So, first off, thanks for taking the time to contribute. We need all the help we can get :thumbsup: -- Found a bug? See how to [report a bug](http://ghdl.readthedocs.io/en/latest/contribute.html#reporting-bugs) and open a [Bug report](https://github.com/ghdl/ghdl/issues/new?template=bug_report.md). -- Got a feature idea? See how to [request enhancements](http://ghdl.readthedocs.io/en/latest/contribute.html#requesting-enhancements) and open a [Feature request](https://github.com/ghdl/ghdl/issues/new?template=feature_request.md). -- Want to contribute modifications to the codebase? See how to [contribute modifications](http://ghdl.readthedocs.io/en/latest/contribute.html#fork-modify-and-pull-request) and open a [Pull Request (PR)](https://github.com/ghdl/ghdl/compare/). +- Found a bug? See how to [report a bug](http://ghdl.github.io/ghdl/contribute.html#reporting-bugs) and open a [Bug report](https://github.com/ghdl/ghdl/issues/new?template=bug_report.md). +- Got a feature idea? See how to [request enhancements](http://ghdl.github.io/ghdl/contribute.html#requesting-enhancements) and open a [Feature request](https://github.com/ghdl/ghdl/issues/new?template=feature_request.md). +- Want to contribute modifications to the codebase? See how to [contribute modifications](http://ghdl.github.io/ghdl/contribute.html#fork-modify-and-pull-request) and open a [Pull Request (PR)](https://github.com/ghdl/ghdl/compare/). - Spread the word. Talk to your friends and colleagues about how awesome GHDL is! - If you want to have any specific talk, e.g. add VHDL design examples, come to [gitter.im/ghdl1/Lobby](https://gitter.im/ghdl1/Lobby). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8270c9713..18c1e6459 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,7 @@ **Description** Please explain the changes you made here. If the feature changes current behaviour, explain why your solution is better. -:rotating_light: Before submitting your PR, please read [contribute](http://ghdl.readthedocs.io/en/latest/contribute.html#fork-modify-and-pull-request) in the [Docs](http://ghdl.readthedocs.io/en/latest/index.html), and review the following checklist: +:rotating_light: Before submitting your PR, please read [contribute](http://ghdl.github.io/ghdl/contribute.html#fork-modify-and-pull-request) in the [Docs](http://ghdl.github.io/ghdl), and review the following checklist: - [ ] DO indicate which issues are either fixed or closed by this PR. See [GitHub Help: Closing issues using keywords](https://help.github.com/articles/closing-issues-via-commit-messages/). @@ -11,13 +11,13 @@ If the feature changes current behaviour, explain why your solution is better. - [ ] DO make sure you are making a pull request against the **master branch** (left side). Also you should start *your branch* off *our master*. - [ ] DO make sure that GHDL can be successfully built. See [Building GHDL](https://github.com/ghdl/ghdl#building-ghdl). - [ ] CONSIDER adding a unit test if your PR resolves an issue. -- [ ] CONSIDER modifying the docs, at least in the TODO, if your contribution is relevant to any of the content. +- [ ] CONSIDER modifying the docs, if your contribution is relevant to any of the content. - [ ] AVOID breaking the continuous integration build. - [ ] AVOID breaking the testsuite. **When contributing to the docs...** -- [ ] DO make sure that the build is successful. See [ghdl/ghdl#572 (issuecomment-390466024)](https://github.com/ghdl/ghdl/issues/572#issuecomment-390466024). +- [ ] DO make sure that the build is successful. **Further comments** diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 9dd708a5c..fe5d0cc18 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -2,12 +2,28 @@ name: 'doc' on: push: - pull_request: jobs: linux: runs-on: ubuntu-latest steps: + - uses: actions/checkout@v2 - - name: build doc - run: ./doc/make.sh + + - name: Build ghdl/doc + run: | + docker build -t ghdl/doc - <<-EOF + FROM ghdl/vunit:llvm + ENV PYTHONPATH=/src/python + EOF + + - uses: buildthedocs/btd@v0 + with: + token: ${{ github.token }} + + - uses: actions/upload-artifact@v2 + with: + name: doc + path: | + doc/_build/html + doc/_build/latex diff --git a/README.md b/README.md index 05704b8b3..7c29b131d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- @@ -9,15 +9,15 @@

- +

- 'cache' workflow Status - 'push' workflow Status @@ -36,14 +36,14 @@ By using a code generator ([LLVM](http://llvm.org/), [GCC](http://gcc.gnu.org/) GHDL runs on [GNU/Linux](http://en.wikipedia.org/wiki/Linux_distribution), [Windows](http://en.wikipedia.org/wiki/Microsoft_Windows) and [macOS](http://en.wikipedia.org/wiki/MacOS); on `x86`, `x86_64`, `armv6/armv7/aarch32` and `aarch64`. You can freely [download](https://github.com/ghdl/ghdl/releases) a binary distribution for your OS, use [GHDL Docker images](https://github.com/ghdl/docker), or try to build it on your own machine (see *'Getting GHDL'* below). -Can write waveforms to a [GHW](http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave), [VCD](https://en.wikipedia.org/wiki/Value_change_dump) or FST file. Combined with a [GUI](http://en.wikipedia.org/wiki/Graphical_user_interface)-based [waveform viewer](https://en.wikipedia.org/wiki/Waveform_viewer) and a good text editor, GHDL is a very powerful tool for writing, testing and simulating your code. +Can write waveforms to a [GHW](http://ghdl.github.io/ghdl/using/Simulation.html?highlight=GHW#cmdoption-wave), [VCD](https://en.wikipedia.org/wiki/Value_change_dump) or FST file. Combined with a [GUI](http://en.wikipedia.org/wiki/Graphical_user_interface)-based [waveform viewer](https://en.wikipedia.org/wiki/Waveform_viewer) and a good text editor, GHDL is a very powerful tool for writing, testing and simulating your code. Supported third party projects: [cocotb](https://github.com/potentialventures/cocotb) (through the [VPI interface](https://en.wikipedia.org/wiki/Verilog_Procedural_Interface)), [OSVVM](http://osvvm.org), [UVVM](https://github.com/UVVM/UVVM), [VUnit](https://vunit.github.io), ... GHDL is free software: - [![GNU General Public License 2](https://img.shields.io/badge/code%20license-GPLv2-bd0000.svg?longCache=true&style=flat-square&label=license&logo=gnu)](https://github.com/ghdl/ghdl/blob/master/COPYING.md) -- [![Creative Commons Attribution-ShareAlike](https://img.shields.io/badge/doc%20license-Creative%20Commons%20Attribution--ShareAlike--4.0-bf7600.svg?longCache=true&style=flat-square&logo=Creative%20Commons)](https://github.com/ghdl/ghdl/blob/master/doc/COPYING_DOC.md) available at [ghdl.rtfd.io](https://ghdl.readthedocs.io). +- [![Creative Commons Attribution-ShareAlike](https://img.shields.io/badge/doc%20license-Creative%20Commons%20Attribution--ShareAlike--4.0-bf7600.svg?longCache=true&style=flat-square&logo=Creative%20Commons)](https://github.com/ghdl/ghdl/blob/master/doc/COPYING_DOC.md) available at [ghdl.github.io/ghdl](https://ghdl.github.io/ghdl). - Some of the runtime libraries, are under different terms; see the individual source files for details. # Getting GHDL @@ -57,7 +57,7 @@ GHDL is free software: ## Building GHDL -GHDL currently supports three different back-ends (code generators). Each has its pros and cons. You can find specific instructions for each of the options in '[Building](https://ghdl.rtfd.io/en/latest/getting/)'. +GHDL currently supports three different back-ends (code generators). Each has its pros and cons. You can find specific instructions for each of the options in '[Building](https://ghdl.github.io/ghdl/getting/)'. ### TL;DR @@ -65,7 +65,7 @@ In order to follow the traditional way to `configure` and `make`, you need an Ad > Alternatively, GNAT GPL can be downloaded anonymously from [libre.adacore.com](http://libre.adacore.com/tools/gnat-gpl-edition/) (later than 2017 is suggested; for x86, 32 or 64 bits). Then, untar and run the *doinstall* script. -> Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as `zlib`. See '[Building](https://ghdl.rtfd.io/en/latest/getting/)' for specific package names. +> Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as `zlib`. See '[Building](https://ghdl.github.io/ghdl/getting/)' for specific package names. To use mcode backend (easiest to build), in the GHDL base directory, configure and build: diff --git a/doc/_static/logo.png b/doc/_static/logo.png new file mode 100644 index 000000000..c0f903a7a Binary files /dev/null and b/doc/_static/logo.png differ diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css index 7efc1c207..4a5cae28e 100644 --- a/doc/_static/theme_overrides.css +++ b/doc/_static/theme_overrides.css @@ -8,14 +8,6 @@ p{font-size:95%;margin-bottom:12px} footer {font-size: 75%;} .rst-footer-buttons {font-size: 140%;} -/*Header and footer margins*/ -footer p {margin-bottom: 0px} -footer hr {margin-bottom: 10px} -[role=navigation] hr {margin-top: 5px} - -/*Do not center main content and allow wider display*/ -.wy-nav-content{margin: auto; max-width: 1020px} - /*Shrink left nav to 260px*/ .wy-nav-side,.rst-versions,.wy-side-nav-search,.wy-menu-vertical{width: 260px} .wy-nav-content-wrap{margin-left:260px;background:#fcfcfc;min-height:100%} @@ -61,10 +53,6 @@ div.wy-menu.rst-pro{display: none !important;max-width: 260px} /*Reduce space between footnotes*/ .footnotes > .wy-table-responsive {margin-top:-12px;margin-bottom:12px} -/* Set text justification in paragraphs and list items to fully justified [borrowed from PoC-Library]*/ -.section p {text-align:justify;} -.simple li {text-align:justify;} - /*Reduce margin below lists*/ .rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px} .rst-content blockquote {margin-bottom: 12px;} diff --git a/doc/conf.py b/doc/conf.py index 69ff6f139..dff335e4d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,7 +1,10 @@ # -*- coding: utf-8 -*- import sys, re -from os.path import abspath, join +from os.path import abspath +from pathlib import Path +from json import dump, loads + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -35,7 +38,7 @@ autodoc_default_options = { 'inherited-members': True, } -templates_path = ['_templates', '_themes'] +templates_path = ['_templates'] # The suffix(es) of source filenames. source_suffix = { @@ -80,9 +83,6 @@ language = None # directories to ignore when looking for source files. exclude_patterns = [] -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True todo_link_only = True @@ -99,17 +99,20 @@ except Exception as ex: # -- Options for HTML output ---------------------------------------------- -html_theme = "sphinx_rtd_theme" - -# Override default css to get a larger width for ReadTheDoc build -html_context = { - 'css_files': [ - 'https://media.readthedocs.org/css/sphinx_rtd_theme.css', - 'https://media.readthedocs.org/css/readthedocs-doc-embed.css', - '_static/theme_overrides.css', - ], +html_theme_options = { + 'logo_only': True, + 'home_breadcrumbs': False, + 'vcs_pageview_mode': 'blob', } +html_context = {} +ctx = Path(__file__).resolve().parent / 'context.json' +if ctx.is_file(): + html_context.update(loads(ctx.open('r').read())) + +html_theme_path = ["."] +html_theme = "_theme" + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/doc/index.rst b/doc/index.rst index 60efcd2a6..8ea01b675 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,10 +1,29 @@ -.. only:: html - - .. exec:: - from helpers import createShields - createShields() - - |SHIELD:gh-logo| |SHIELD:gitter| |SHIELD:code-lic| |SHIELD:doc-lic| |SHIELD:travis-ci| |SHIELD:appveyor| |SHIELD:release| +.. exec:: + from helpers import createShields + createShields() + +GHDL +#### + +.. image:: _static/logo.png + :width: 400 px + :align: center + :target: https://github.com/ghdl/ghdl-cosim + +.. raw:: html + +

+ + + + + +

.. only:: html diff --git a/doc/requirements.txt b/doc/requirements.txt index 7e7fe40ed..e632e6afd 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,7 +1,6 @@ #-r ../requirements.txt -sphinx>=1.5.2 +sphinx>=3.0.0 recommonmark -sphinx_rtd_theme python-dateutil # sphinxcontrib-textstyle>=0.2.1 # sphinxcontrib-spelling>=2.2.0 diff --git a/doc/shields.json b/doc/shields.json index 8224fe0f9..da81ca57d 100644 --- a/doc/shields.json +++ b/doc/shields.json @@ -1,28 +1,4 @@ { - "travis-ci": { - "src": "travis/ghdl/ghdl/master.svg?logo=travis", - "target": "https://travis-ci.org/ghdl/ghdl", - "alt": "Build status by Travis-CI" }, - "appveyor": { - "src": "appveyor/ci/tgingold/ghdl-psgys/master.svg?logo=appveyor&logoColor=aab2ab", - "target": "https://ci.appveyor.com/project/tgingold/ghdl-psgys/branch/master", - "alt": "Build status by AppVeyor" }, - "release": { - "src": "github/release/ghdl/ghdl.svg?label=latest%20release", - "target": "gh:ghdl/ghdl/releases", - "alt": "Latest release" }, - "code-lic": { - "src": "badge/code%20license-GPLv2-bd0000.svg?label=license&logo=gnu", - "target": "Licenses.html", - "alt": "GNU General Public License 2" }, - "doc-lic": { - "src": "badge/doc%20license-CC--BY--SA--4.0-aab2ab.svg?", - "target": "Licenses.html", - "alt": "Creative Commons Attribution-ShareAlike 4.0" }, - "gitter": { - "src": "badge/chat-on%20gitter-4db797.svg?logo=gitter&logoColor=4db797", - "target": "https://gitter.im/ghdl1/Lobby", - "alt": "Talk to us on Gitter" }, "issues-new": { "src": "badge/new-issue-yellowgreen.svg?logo=github", "target": "gh:ghdl/ghdl/issues/new", @@ -59,8 +35,8 @@ "src": "github/contributors/ghdl/ghdl.svg?logo=github", "target": "gh:ghdl/ghdl/graphs/contributors", "alt": "Contributors" }, - "gh-logo": { - "src": "badge/-ghdl/ghdl-323131.svg?logo=github", - "target": "gh:ghdl/ghdl", - "alt": "Source Code on GitHub" } + "gitter": { + "src": "badge/chat-on%20gitter-4db797.svg?logo=gitter&logoColor=4db797", + "target": "https://gitter.im/ghdl1/Lobby", + "alt": "Talk to us on Gitter" } } diff --git a/logo.png b/logo.png deleted file mode 100644 index c0f903a7a..000000000 Binary files a/logo.png and /dev/null differ -- cgit v1.2.3