Fontbakery: Documentation page seems partially broken

[felipesanches]

It may be related to the recent PR #2800

[felipesanches]

I thought this was related to the changes made to add a youtube video to the page, but after reverting that, the problem persists. I'll have to look more carefully at the syntax used throughout that fist page of docs.

[chrissimpkins]

I took a look and nothing immediately jumps out Felipe. Odd. It was just the video block that was removed in the documentation files.

There is a good documentation build at f724c2e1 that you can point to @ https://font-bakery.readthedocs.io/en/stable/ during the fix.

[chrissimpkins]

I ran https://pypi.org/project/restructuredtext-lint/ over the index.rst file:

Details

ERROR index.rst:12 Unknown directive type "toctree".
ERROR index.rst:18 Unknown directive type "toctree".
ERROR index.rst:26 Unknown directive type "toctree".
ERROR index.rst:35 Unknown directive type "toctree".
ERROR index.rst:41 Unknown directive type "toctree".
ERROR index.rst:51 Unknown interpreted text role "ref".
ERROR index.rst:52 Unknown interpreted text role "ref".

I think that these are just Sphinx-specific idioms and not supported in the linter?

rst should be banished... It is such a PIA to work with.

[felipesanches]

it gives me the impression that the parser was updated server-side on readthedocs and now supports a different subset of the syntax

[felipesanches]

it is good now, but I suppose we may have to get back to it after the next release as it may break again. Or maybe not. It may be an intermmitent server-side condition at readthedocs.org

We'll reopen the issue if the problem creeps back later

[chrissimpkins]

Possible to pin dependency versions in the docs requirements file?

[felipesanches]

interesting idea... I don't know.

[felipesanches]

I also changed the both the fontbakery.com redirect and the GitHub repo README.md link to both point to stable instead of latest. And made the redirect faster. It was 2 seconds and now it redirects within a single second of loading fontbakery.com.

In my opinion it could even immediately redirect, but it seems some people may still want to have access to those links to the old dashboard.

[davelab6]

Thanks for the fast work on this Chris and Felipe! :)

[felipesanches]

We'll reopen the issue if the problem creeps back later

And indeed the problem is back as I have just released FB v0.7.23 and "stable" on readthedocs is now a new build of the docs which is also broken. We will have to look closer at what changed in the supported syntax.

[felipesanches]

I got it!

Sphinx 1.4 requires a different approach to configuring mixed rst+markdown parsing.

[felipesanches]

This is now fixed, but requires a new release to trigger an update on latest docs. So I'll do it now ;-)