Landing site for GHDL

[eine]

Demo available.

---

• The enhancement of the documentation which started almost a year ago has been recently merged to master (see New documentation structure #482).
• The migration from tgingold/ghdl to the new organization is almost done (GHDL, a GitHub organization #500). GitHub, Travis and RTD are already fixed. Only AppVeyor is to be updated (see 500#issuecomment-353274561).
• Travis stages have been recently introduced in the build system (see Use docker multistage builds, travis stages, yaml aliases and deploy to dockerhub #489). Also, dockerhub is integrated in the main repo, although credentials need to be configured, yet.

This issue is an attempt to follow these efforts towards making GHDL easier to start with for new users. More precisely, it is a proposal to replace ghdl.free.fr, which is mostly deprecated, but has some interesting section 'concepts': http://ghdl.free.fr/site/pmwiki.php?n=Main.Download

This is just a proof of concept to put some content in ghdl.github.io. To do so, we would create a new repo in the organization (ghdl/ghdl.github.io). Then, we can automate the deployment in travis by adding a (last) stage to the build. In fact, having an organization makes it safer to automate the deployment without compromising the main repo, as explained in #477.

Related to the URL, if @tgingold is okay with it, ghdl.github.io can be a redirected to ghdl.free.fr, or the other way. Indeed, we can use an external domain but keep the page hosted at GitHub. If not, they can be just separate sites.

---

The proposed site is built from Markdown and reStructuredText sources with hugo, as explained in #477. Indeed, the structure explained there can be seen in the demo site. Mostly md sources are saved in ghdl-io, while mostly rst sources are kept in doc.

I wrote the template from scratch with tachyons. This means it is not feature-complete, but is is lightweight and simple (no social links, no google-analytics, etc.). The landing page is almost finished. The rest of the pages still need some work (i.e. code highlighting).

Some interesting features:

• The whole site is built in 1.35s in a docker container. A local server can be started to edit the sources and livereload the site.
• The commit and date of the build are shown in the footer.
• The date of the last modification of each file is extracted from git.
• Headings are anchored, and these are explicitly shown. I am working to show them in the sidebar too.
• A 'Edit me on Github' button is shown in the header of each page (except the landing page).
• Content from issues, PRs and comments here can be copied mostly raw to the documentation.
• If the wiki is enabled in the GHDL repo (which is a 'hidden' repo on its own), the content from the wiki (which is Markdown) can be seamlessly integrated in the site.
• Hugo support marking content as Draft or for Future release, which is quite handy to keep todos hidden, but easily show them.

Work in progress:

• Expandable/collapsible sidebar up to the first heading level.
• Optional floating table of contents for the content in each article/page.
• Optionally show/hide the sidebar, half of the footer and the header.
• Make the landing page responsive. Currently it is ok for large screens, somehow ok for medium screens, and totally broken for mobile devices.
• Add latest commits as 'news'. See in gohugo.io. Also, see comments in update tgingold/ghdl refs to ghdl/ghdl #503.
• Integrate Sphinx/RTD sources properly. At now, rst sources can be easily added, but sphinx specific syntax produces errors. E.g. contribute/contribute.
• Integrate Pandoc. Need to guess which syntax limitations are involved in order to use the same sources for the github wiki, hugo and pandoc (and sphinx).
• 'Intelligent' cross-references.
• Embedded demo/tutorial with play-with-docker and xterm.js. See http://waves.pshdl.org/
• Day/night color as in docs.docker.com/get-started.

Ideally, I want to embed Sphinx into the build procedure of the site, so that ghdl.free.fr/ghdl.github.io is a superset of RTD, without content conflicts at all, just two visualizations of the same sources.

---

@tgingold, @Paebbels note that, if you are not ok with having two sites with similar content, you can still consider the landing page only. In the end, the product is a static site (a few html, css and js files).

As I said, the template is written from scratch, so any color, border, size, font type... can be modified.

[Paebbels]

I like your pushing in that direction.

The landing page looks good, but the colors might be a bit too gray :). I'm think of people having issues in reading it con screens. Anyhow the structure and simplicity looks good.

I would suggest to slowdown the animation.

I have still mixed feelings about integration of RTD. But yes, GHDL is nor an organisation, so we have our own GitHub page for deployment. So I'll wait for your next proof of concept uploads.

[eine]

I like your pushing in that direction.

So glad to hear it!

The landing page looks good, but the colors might be a bit too gray :). I'm think of people having issues in reading it con screens. Anyhow the structure and simplicity looks good.

I know, I've never been good when choosing color palettes for a general public :S. However, I somehow checked it. See

.light-silver { color: #AAAAAA }
.bg-near-black { background-color: #111111 }

in http://tachyons.io/docs/themes/skins/

It scores 8.13, which I don't know whether it is too much, or not enough.

Anyway, there is quite a complete palette there, so feel free to suggest alternatives.

I would suggest to slowdown the animation.

Agree. Also, I want to make it fade-in/fade-out or introduce any other visual feedback to let the user now that a single box is changed in each step (it is a sliding window). That is, there are 9 in total.

I have still mixed feelings about integration of RTD. But yes, GHDL is nor an organisation, so we have our own GitHub page for deployment. So I'll wait for your next proof of concept uploads.

About the organisation itself, as you see I consided github.com/ghdl and github.com/ghdl/ghdl to be somehow equivalent, meaning the latter is 'THE REPO', and any other are just auxiliary. I don't know if we should make it explicit that there is an organization, a main repo, an other repos.

The implication of this is that ghdl.github.io/ghdl is also available, which would be branch gh-pages in this repo. Therefore, it'd be posible to have the equivalent to RTD hosted here and the full site in the separate repo. I don't like this approach. Just writing it here to have all the possibilities explained.

[Paebbels]

The URL ghdl.github.io/ghdl creates to much confusion ...

I don't like the loose branch in a multi rooted Git repository. That's not the idea of Git. Therefore users should use a separate repository. It's just a silly solution to spare an additional URL by GitHub.

[tgingold]

On 22 Dec 2017, at 07:50, 1138-4EB ***@***.***> wrote: Demo available.

That's great! I was never good at writing website; thank you for pushing in that direction. [...]

Related to the URL, if @tgingold is okay with it, ghdl.github.io can be a redirected to ghdl.free.fr, or the other way. Indeed, we can use an external domain but keep the page hosted at GitHub. If not, they can be just separate sites.

I think ghdl.free.fr can be a redirection to ghdl.github.io, that would be simpler. [...]

Ideally, I want to embed Sphinx into the build procedure of the site, so that ghdl.free.fr/ghdl.github.io is a superset of RTD, without content conflicts at all, just two visualizations of the same sources. @tgingold, @Paebbels note that, if you are not ok with having two sites with similar content, you can still consider the landing page only. In the end, the product is a static site (a few html, css and js files).

Having a static site is fine, as that's simpler to setup. I am ok with having both RTD (which could be considered as a book) and the website. We will see how it works.

As I said, the template is written from scratch, so any color, border, size, font type... can be modified.

Up to you; I am not good at all in this topic. Tristan.

[branylagaffe]

Hey thank you @1138-4eb for your website demo, I also think GHDL deserves it's own (great looking (sorry ghdl.free.fr)) website.

About the website, IMO we should base the overall layout on an existing framework.

It would be:

• Easier to build
• Easier to maintain
• Right now the "mobile" version is a mess
• (maybe plenty others reasons)

Tell me what do you think about that.

[eine]

@tgingold:

That's great! I was never good at writing website; thank you for pushing in that direction.

It's not the most comfortable environment for any of us in this community. But tools have evolved quite a lot. I hope we can come up with a solution we all understand, at least, in order to edit the content, add/remove, etc. Indeed, we can push the automation parts to master at a slow rythm, so that we all learn in the process. We might name it the 'How to make modern web pages without being a frontend designer' task.

I think ghdl.free.fr can be a redirection to ghdl.github.io, that would be simpler.

In order to get rid of deprecated pages (such as http://ghdl.free.fr/site/pmwiki.php?n=Main.Download) appearing in the search engines I think we should make this carefully.

At now, there is some host which is not GitHub involved. Do you want to keep using it? I ask this because we can make DNS services point to GitHub directly, and make GitHub serve ghdl.github.io as ghdl.free.fr. However, this would prevent you from using the old host, unless you have any other domain, or you access through IP.

If you want to keep ghdl.free.fr, I think you should move all the content to a subdir (say old), and have both a custom 404 and a redirection in the root. Then any user following deprecated links will see a message telling that the new site is at ghdl.github.io, and that it is going to be redirected in a few seconds. There might be other technical alternatives to achieve this which I am not aware of. Please, tell me if you know any.

NOTE: I cloned ghdl.free.fr with httrack, and there is a lot of 'hidden' content there (120MB). Mostly old releases (from 0.1 to 0.29, including windows installers in the latest).

Having a static site is fine, as that's simpler to setup.

I meant that the product is a static site, once the site is generated with the automation scripts, . That is, the production environment is easier to setup (just a file server, 30 lines in golang). However, because "we" "want" to have it automated from md or rst sources in the repo, and have it hosted in github pages (which is a different repo), the build & deployment process is not so simple. It is not much, but there are 70 lines of 'simplicity' involved: git clone sources, exec hugo, [exec other tools,] git clone target, compare, if diff -> commit, if commit -> push.

I am ok with having both RTD (which could be considered as a book) and the website. We will see how it works.

I really like this approach. I.e. conceiving RTD as a book, or the main chapters in a book, and the site being the cover page, preface, appendices, etc.

---

@Birate:

Hey thank you @1138-4eb for your website demo, I also think GHDL deserves it's own (great looking (sorry ghdl.free.fr)) website.

I don't think we need to feel sorry. We are talking about a not-complete effort started 10 years ago. GHDL didn't use GitHub. Wikis were the alternative to CMS such as WordPress, Joomla, etc. In the end, I think it is great looking if we see the context.

About the website, IMO we should base the overall layout on an existing framework.
(...)
Tell me what do you think about that.

Don't take me wrong, but as far as I completely agree with you, I think that these statements are quite empty. I am using a framework, which is hugo for the 'backend' (i.e. generator or builder) and tachyons.io along with jQuery for the frontrend. See About this site. You can find the build procedure in the gh-pages.sh script linked above.

NOTE it might be possible that this exact info was not online when you visited the page (although I think it was). It is equally ok if it was there but you didn't see it. Once again, I don't want to sound rude at all. tho it is difficult when writing.

Right now the "mobile" version is a mess

I already stated that the mobile version of the landing page is not correct: Make the landing page responsive. Currently it is ok for large screens, somehow ok for medium screens, and totally broken for mobile devices. So, I agree with you. However, I don't think that it can be extended to all the site. Sure, there are things to fix but I believe that every page except the landing page is ok. Let me be more explicit:

• The header and footer take too much space. I already stated that I want to optionally hide half of them (the badges) or completely.
• I want to make the sidebar expandable/collapsable too. I mean to the left, i.e. hide/show.
• I already made the template take 100% of the height of the screen, disabled the overflow in the main window and enabled vertical scroll for the sidebar and the main content. The resulting UX experience is that you can scroll the sidebar and the main content independently. I find pages with the sidebar fixed to top really disgusting, because you are forced to leave the current line in order to check the TOC.

NOTE: the mess in the landing page is due to the height being fixed to the height of the screen. Disabling that CSS limitation in small screens fixes it. The same applies to the menu in the header. There is no dropdown in small screens, because I didn't introduce JavaScript yet. The only JavaScript feature is the animated slider.

Easier to build

I think it is quite easy to build right now. The complexity is related to the fact that we host sources in a git repo, the product in a different repo, and we want to have it automated. Locally, it is as complex as hugo server -DEF and browse localhost:1313. Indeed, the main derived feature of this build procedure is that we can have a 20MB "portable doc development" environment, so that people can easier contribute writting guides and tutorials.

NOTE: I am very interested in having a lightweight jupyter-alike system for VHDL development. That is: write your code in markdown; preview it on-the-go in the browser; have code blocks indentified and allow to run GHDL; show the logs and waveforms below the code blocks. Save either the source or the product and share on GitHub/Gogs/Gitea/GitLab...!

There is also complexity involved in trying to "merge" RTD sources with/in a different site. But this is a conflict we need to handle with any framework, unless we use RTD exclusively. This would mean designing a template for Sphinx from scratch and writting every custom procedure in Python. Once again, let's be more explicit about this option:

• It seems to be the most straightforward. Agree.
• The template needs not to be written from scratch, it can be based on existing themes: http://www.writethedocs.org/guide/tools/sphinx-themes/ .
• Need to guess:
  • Declare lists and structs with metainformation in formats such as YAML or TOML and have it interpreted by Sphinx.
  • Generate multiple views for the same content.
  • Define different views for the content in different sections, but keeping some common parts.
  • Tags, categories, taxonomies.
  • Drafts and content for Future publication.
  • Lightweight server to allow edition with livereaload.
  • Handle lists of content and single pages without explictly generating every index/toc.
  • ...

Sincerely, I don't feel comfortable at all doing all of that in Python exclusively, because that is the only option available in RTD. I want to be able to use the better tool and language for each task. E.g., execute curl and jq in a bash script to get info about releases/milestones from the GitHub API and have the 'Release notes' content automatically written in md or rst. No matter if the content is later pushed to GitHub releases, RTD or a different site. 80-90MB of Python runtime to do that? No, please.

Then, if we introduce Travis because we want to execute different 'pre-process' tools to set the sources which will be then rendered by proper generators (be Sphinx, be hugo, be any other), why not make the best of it? I.e., analise all possible approaches to make GHDL a project where it is easier to contribute for users coming from different contexts?

Easier to maintain

Actual workflow:

• Develop GHDL.
• Write documentation by hand in rst format. Save it in doc.
• If new content is added or old content is removed, check if the sidebar needs a modification to reflect it.
• If a new release is published, edit the corresponding source in RTD, the README.md, and the release notes in Github releases. Note that the first is in rst format, while the other two are in markdown; so, the same content must be written twice.
• Handle labels and tags for html generation and for latex generation in the same sources, which makes it difficult to preview the result.
• A PDF version is generated for every push. This is done in the background, but is known to require a full LaTeX installation and not to be fast at all, compared to the generation of the HTML version.

My proposed workflow:

• Develop GHDL.
• Extract the documentation from explicitly formatted comments in the ADA sources. Not-accepted for now: Documentation extraction from sources #484.
  • So, write the documentation by hand in rst format. Save it in doc. Allow rst and md, but prefer rst.
• Write the site (landing and 'community content' such as guides, tutorials, docker images, guis, etc.) in ghdl-io. Allow md and rst, but prefer md.
• If new content is added or old content is removed, do nothing. The sidebar and menus are generated automatically. At most, set a weight to the new content, to decide where it should appear in lists.
• If a new release is published, do no nothing. It is updated automatically.
• Have a plain template to generate the site in a format suitable for Pandoc. Handle the LaTeX template and auxiliary LaTeX-only content separately.
• Generate PDF versions for releases only. Have multiple HTML versions, if wanted.

Why I prefer md for 'community content' and rst for the documentation? Because GitHub issues, PRs, readmes, etc. default to markdown, so it is more familiar to most of potential contributors. These are expected to contribute mostly with atomic material: a guide, instructions for a new/different platform, some external tool... However, rst and sphinx are better for cross-references (see gohugo.io/content-management/cross-references), which is a must if GHDL commands, options, arguments and internal are documented by hand, as it is now.

(maybe plenty others reasons)

Please, do not hesitate to propose additional tools, alternatives or state why you think that hugo, tachyons, jquery and sphinx are not the best framework.

Just for you to have a broader view. This is the list of currently available Hugo themes: https://themes.gohugo.io/ That is, we can use any of those without changing the sources. You can pull branch builders from https://github.com/1138-4EB/ghdl/ and modify the theme in ghdl-io/config.toml, as explained in https://gohugo.io/themes/installing-and-using-themes/

This means that I am open to using themes based on different toolsets, such as Bootstrap, Foundation, Angular, Vue... I started a new one from scratch because I felt that none of the existing fullfils our requirements, and it is easier to start from scratch taking things from here and there, than starting with an existing theme and leaving it clean prior to adding missing features. However, please, lets discuss about it. There are quite a lot of different options, and I'd be really pleased to hear other opinions on the workflow as a whole.

For example, I stated above that I haven't introduced JavaScript yet, because I'd like to use Vue.js. But I am not sure if we need it or we can get along with raw JavaScript. Related to this, see filebrowser/filebrowser#302 (package.json), which comes from #111, and there is a draft here.

On top of that, these are references I've had a look at:

• https://pandoc.org/
• http://docutils.sourceforge.net/index.html
• http://www.sphinx-doc.org/en/stable/
• https://readthedocs.org/
• http://jinja.pocoo.org/
• https://github.com/jupyter/nbconvert
• http://jupyter.org/
• http://rmarkdown.rstudio.com/formats.html
• https://github.com/gettalong/kramdown
• https://jekyllrb.com/
• https://github.com/GitbookIO/gitbook
• https://github.com/miekg/mmark
  • https://github.com/miekg/gobook
  • https://miek.nl/files/go/Learning-Go-latest.pdf
  • https://miek.nl/go/
  • https://github.com/miekg/learninggo

[eine]

Small update:

• Running Sphinx out of RTD is straightforward, so I created a new ghdl/ext:sphinx docker image, and I execute it in Travis, just before Hugo. Because contents are just merged, this is the result:
  • https://1138-4eb.github.io/ghdl/
  • https://1138-4eb.github.io/ghdl/doc/

Note that I used Sphinx, not RTD. As a result, a single version of the docs is shown.

This is because RTD is not meant to be used out of RTD.org at all:

• make html works but readthedocs-build fails inside readthedocs/build:latest readthedocs/readthedocs-build#35
• rtfd/readthedocs-docker-images#47
• The procedure described in CONTRIBUTING.rst is broken readthedocs/readthedocs-docker-images#48
• :github_url: as a theme option readthedocs/sphinx_rtd_theme#529 [SOLVED]

[Paebbels]

(Haven't read the linked issues yet...)

So its not possible to use the RTD docker image? It would bring us rendering to PDF via LaTeX.
I consider this a great benefit of RTD.

But yes, compiling documentation on Travis-CI brings us a faster and mor stable compilation. RTD has performance problems due to their low performance servers. I needed to negotiate an exception for PoC, because wie are compiling for several minutes.

[eine]

(Haven't read the linked issues yet...)

Long story short: RTD is monolithic. It is meant to be used as a web service. Everything is executed in a 8.5GB docker container: all possible python versions, dependencies, etc. There is little work done towards using multiple less resource-hungry images.

So its not possible to use the RTD docker image? It would bring us rendering to PDF via LaTeX.
I consider this a great benefit of RTD.

There are two different issues here:

• We do not need any RTD resource at all. We can have it done with Sphinx and LaTeX. To do so, we need one or multiple docker images with the required dependencies. I propose using ghdl/ext:sphinx for everyday (just html) and ghdl/ext:latex for releases (PDF).
• It is possible to use the RTD 8.5GB image, which includes not only minimum dependencies but also a lot of auxiliary packages, such as plantuml. Indeed, in all the links above I use this image. Yet, functionally it is the same as having sphinx + latex + extras, because no RTD feature can be used.

When I say 'RTD feature' I mean the "multiple version" box in the bottom left. Do you miss any other feature?

But yes, compiling documentation on Travis-CI brings us a faster and mor stable compilation. RTD has performance problems due to their low performance servers. I needed to negotiate an exception for PoC, because wie are compiling for several minutes.

This is ready. Now I'm trying to modify the readthedocs template to add some links the the home of the site.

Do you want to try building PoC inside travis?

---

Note, I expect RTD to have equivalent images to ghdl/ext:sphinx (340MB) and ghdl/ext:latex (2GB) at some point, which would allow us to stop maintaining these. But, for now, 8.5GB is not acceptable at all.

[Paebbels]

I don't think the multiple versions/doc builds feature is needed for GHDL.

Are there LaTeX only Docker images? LaTeX is a very big bundle and requires a lot of "normal" installation time.

How does Travis-CI handle the download time of a multi GB image? Do they have Docker caches?

---

I'm currently building PoCs documentation in RTD. It requires more than 30 minutes to finish due to the low performance servers and slot disks. My local PC is much faster. I experimented with Travis-CI and a GitHub.io static page. Unfortunately, PoC needs the multiple versions/branches features.

[eine]

I don't think the multiple versions/doc builds feature is needed for GHDL.

Then, we are almost ready to leave RTD.org, but keep using the same sources and the same template. The only missing issue is to link the 'Edit on GitHub' button to the proper URLs (see readthedocs/sphinx_rtd_theme#529).

Are there LaTeX only Docker images? LaTeX is a very big bundle and requires a lot of "normal" installation time.

There are plenty of them. But I think we should use our own for now, in order to install minimum packages only. Note that installation time is irrelevant, because we use travis stages and we avoid building images every time.

How does Travis-CI handle the download time of a multi GB image? Do they have Docker caches?

See #489 (comment)

---

I'm currently building PoCs documentation in RTD. It requires more than 30 minutes to finish due to the low performance servers and slot disks. My local PC is much faster. I experimented with Travis-CI and a GitHub.io static page. Unfortunately, PoC needs the multiple versions/branches features.

Did you get the 'Edit on GitHub' feature to work?

Is that list of versions/branches described in any of the sources or is it configured through the RTD.org frontend?

[Paebbels]

No there is no edit link.

I remember only the of "active" branches in the RTD web GUI. I haven't seen this as an option for .readthedocs.yml.

[eine]

Well. An hour ago I was pretty decided to write an alternative implementation of RTD. That is, a bash script that reads a configuration .yml and allows to build multiple versions in Travis. First, I thought about what the name should be: bash-rtd, writethedocs, buildthedocs... While checking if they exist, I found:

• https://pypi.python.org/pypi/buildthedocs
• https://docs.typo3.org/typo3cms/extensions/sphinx/Introduction/Index.html

So I'm reviewing those.

[eine]

Just some follow up on this issue:

In the end, I spent yesterday setting up the alpha version of github.com/buildthedocs:

• buildthedocs/btd: main repo. Single shell script to build multiple versions of the documentation with Sphinx and LaTeX, and get a HTML site and a bunch of PDFs.
• buildthedocs.github.io: dogfooding. The HTML output of btd building it's own documentation (buildthedocs/btd/doc).
• buildthedocs/sphinx_btd_theme: fork of rtfd/sphinx_rtd_theme. Right now, it is a plain fork. It is expected to include cherry-picked enhancements from github.com/TYPO3-Documentation/t3SphinxThemeRtd.

Current status:

• Building multiple versions and having a 'plain' landing page for documentations is ready:
  • 1138-4eb.github.io/ghdl/doc/
    • Note that 'builders' is the development or master branch in my fork. 'master' has a special meaning there.
• 'Edit me on Github' works. See :github_url: as a theme option readthedocs/sphinx_rtd_theme#529.
  • It 'always' points to the source of the master branch in ghdl/ghdl (see 1138-4eb.github.io/ghdl/doc/builders). Do we like this behaviour?
    • Note that this feature is 'broken' in readthedocs for both, ghdl and PoC.
• No 'versions' box is shown in the bottom-left, yet.
  • I have to guess how to either activate or add it.
• PDFs not explicitly linked. But available. Will be linked when the 'versions' box is added.
  • https://1138-4eb.github.io/ghdl/doc/pdf/GHDL_builders.pdf
  • https://1138-4eb.github.io/ghdl/doc/pdf/GHDL_v0.35.pdf
  • https://1138-4eb.github.io/ghdl/doc/pdf/GHDL_v0.34.pdf

---

Execution time to build the three versions and deploy to GitHub Pages: 6min43s. I expect to improve it by building a single version each time (that corresponding to the active branch) and let the rest untouched, as long as they exist. This is closer to readthedocs' behaviour.

---

@tgingold , @Paebbels any guess about all the warnings we get? I am mostly concerned about the unknown option warnings.

/src/doc/appendix/Meta.rst:42: WARNING: Content block expected for the "code" directive; none found.
/src/doc/appendix/Meta.rst:10: WARNING: Duplicate explicit target name: "#294".
/src/doc/building/gcc/GNULinux-GNAT.rst:17: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/doc/building/gcc/GNULinux-GNAT.rst:20: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/doc/building/gcc/GNULinux-GNAT.rst:23: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/doc/getting/Releases.rst:116: WARNING: Malformed table.
/src/doc/licenses.rst:13: WARNING: Duplicate explicit target name: "more info".
/src/doc/building/PrecompileVendorPrimitives.rst:179: WARNING: Could not lex literal_block as "PowerShell". Highlighting skipped.
/src/doc/building/mcode/Windows-GNATGPL.rst:28: WARNING: Pygments lexer name 'plain' is not known
/src/doc/getting/Releases.rst:160: WARNING: undefined label: getting:require (if the link has no caption the label must precede a section header)
/src/doc/references/CommandReference.rst:85: WARNING: unknown option: --format=
/src/doc/references/CommandReference.rst:87: WARNING: unknown option: --format=html2
/src/doc/references/CommandReference.rst:88: WARNING: unknown option: --format=css
/src/doc/references/CommandReference.rst:88: WARNING: undefined label: cross-reference_command (if the link has no caption the label must precede a section header)
/src/doc/references/ImplementationOfVHDL.rst:186: WARNING: unknown option: --work=NAME
/src/doc/references/ImplementationOfVHDL.rst:216: WARNING: unknown option: --work=
/src/doc/references/ImplementationOfVHDL.rst:220: WARNING: unknown option: --std=93c
/src/doc/references/ImplementationOfVHDL.rst:220: WARNING: unknown option: -fexplicit
/src/doc/references/ImplementationOfVHDL.rst:220: WARNING: unknown option: -frelaxed-rules
/src/doc/references/ImplementationOfVHDL.rst:220: WARNING: unknown option: --warn-no-vital-generic
/src/doc/references/ImplementationOfVHDL.rst:334: WARNING: undefined label: elaboration_command (if the link has no caption the label must precede a section header)
/src/doc/using/InvokingGHDL.rst:29: WARNING: unknown option: --PREFIX
/src/doc/using/InvokingGHDL.rst:50: WARNING: undefined label: ghdl_options (if the link has no caption the label must precede a section header)
/src/doc/using/InvokingGHDL.rst:68: WARNING: unknown option: --work=NAME
/src/doc/using/InvokingGHDL.rst:68: WARNING: undefined label: ghdl_options (if the link has no caption the label must precede a section header)
/src/doc/using/InvokingGHDL.rst:70: WARNING: unknown option: -o
/src/doc/using/InvokingGHDL.rst:82: WARNING: undefined label: elaboration_command (if the link has no caption the label must precede a section header)
/src/doc/using/InvokingGHDL.rst:235: WARNING: unknown option: -P
/src/doc/using/InvokingGHDL.rst:288: WARNING: unknown option: --workdir
/src/doc/using/InvokingGHDL.rst:432: WARNING: unknown option: --workdir
/src/doc/using/InvokingGHDL.rst:432: WARNING: unknown option: -P
/src/doc/using/InvokingGHDL.rst:444: WARNING: unknown option: --work
/src/doc/using/InvokingGHDL.rst:444: WARNING: unknown option: --workdir
/src/doc/using/InvokingGHDL.rst:583: WARNING: unknown option: --ieee=synopsys
/src/doc/using/InvokingGHDL.rst:583: WARNING: unknown option: --ieee=mentor
/src/doc/using/InvokingGHDL.rst:640: WARNING: undefined label: ghdl_options (if the link has no caption the label must precede a section header)
/src/doc/using/QuickStartGuide.rst:192: WARNING: unknown option: --workdir=work
/src/doc/using/Simulation.rst:54: WARNING: unknown option: --assert-level=none
/src/doc/using/Simulation.rst:179: WARNING: unknown option: --vcd
/src/doc/using/Simulation.rst:184: WARNING: unknown option: --vcdgz
/src/doc/using/Simulation.rst:270: WARNING: unknown option: --disp-tree
/src/doc/using/Simulation.rst:276: WARNING: unknown option: dir
/src/doc/using/Simulation.rst:278: WARNING: unknown option: --format=html2
/src/doc/using/Simulation.rst:280: WARNING: unknown option: --format=css

---

Right now, this is used in GHDL like this:

curl -L https://raw.githubusercontent.com/buildthedocs/btd/master/btd.sh | sh -s build -v "builders,v0.35,v0.34"
mv ../btd_builds/html ghdl-io/static/doc/
# Execute Hugo
# Deploy

---

@Paebbels , this should work for PoC too:

git clone https://github.com/VLSI-EDA/PoC 
cd PoC
curl -L https://raw.githubusercontent.com/buildthedocs/btd/master/btd.sh | sh -s build -v "release,stable" -i docs

However, I have not included the step which installs custom dependencies, yet. I don't want to do it on-the-fly, but have them preinstalled/cached.

[tgingold]

Most of the warnings are ok: options like --ieee are documented with all the choices but referenced with a generic name.

I Haven't yet found a way to fix them.

[cmarqu]

In the meantime, http://ghdl.free.fr/ is much worse than https://ghdl.github.io/ghdl/, yet it's the first hit for "ghdl" on Google.