Introduce DOCtor-RST #613

OskarStark · 2020-01-31T15:02:10Z

DOCtor-RST is a linting tool (which runs as GithubAction), which is used at symfony-docs, Sonata and EasyAdminBundle.

It checks the rst files for some specific conventions.

You can see it in Action here: https://github.com/symfony/symfony-docs/pull/13006/checks?check_run_id=414955239

We are using it since a few months for the symfony-docs and is developed by me 😄

https://github.com/OskarStark/doctor-rst

alcaeus · 2020-01-31T15:37:57Z

@OskarStark could you please add a comment to tell me what DOCtor-RST does? ;)

OskarStark · 2020-01-31T15:41:46Z

Sure, I updated the PR header 👍

PS: Best reviewed commit-by-commit

malarzm · 2020-02-01T09:33:10Z

Resources/doc/config.rst

@@ -343,17 +343,13 @@ following syntax:
            </doctrine_mongodb:config>
        </container>

-Now you can retrieve the configured services connection services:
-
-.. code-block:: php


Why is this a bad thing?

It’s not called bad, but more noise then you need and it reads more fluently.
Also you have highlighted code block in PHPStorm for example

Ah ok, I thought it was the php part that would allow IDEs to understand there's PHP (not brainfuck for one) inside the code block (or tell renderer later it should use PHP rules for code highlighting)

malarzm

This looks great, I'd love to have it run on ODM's docs as well 🎉

OskarStark · 2020-02-01T09:59:07Z

Thank you 😊 my plan is to add it to all doctrine repositories 😊✌🏻

alcaeus

LGTM. @SenseException can we test this on the website before rolling it out? I would like to confirm that the changes to code blocks don't have unwanted side effects.

SenseException · 2020-02-04T22:33:12Z

The website only reads the docs of repository branches from the .doctrine-project.json file on master. Maybe I can test it locally in this case.

SenseException

I get this error during the docs-build: /!\ Error while processing "code-block" directive in "form": Unknown language: html+twig

OskarStark · 2020-02-11T09:32:46Z

Hi @SenseException can you tell me which Sphinx version you are using or can I see your setup?

We at Sonata-Project and Symfony (docs) added a GithubActions workflow to build the docs and see if its working. Are you interested in this too? If yes I could provide one in a separate PR 👍

alcaeus · 2020-02-11T10:30:39Z

We at Sonata-Project and Symfony (docs) added a GithubActions workflow to build the docs and see if its working. Are you interested in this too?

Yes please. 😍

SenseException · 2020-02-11T19:53:22Z

The Doctrine website is currently using https://github.com/doctrine/rst-parser for creating the docs, but having Sphinx would be great too. It can create a HTML documentation pretty fast for a big amount of ReStructuredText files.

OskarStark · 2020-02-11T19:55:31Z

Hmm I have no experience with the rst parser. Does my PR works after dropping this commit? ec846d5

Can you do and try or shall I drop the commit from this PR?

Or maybe just tell the parser to render twig the same as jinja? 🤔

SenseException · 2020-02-11T20:11:17Z

For now please use html+jinja again. Did DOCtor marked this as an issue?

I wrote a small example from the parser and pushed it into https://github.com/SenseException/rst-builder. I think it misses a few implementations that got directly implemented into https://github.com/doctrine/doctrine-website itself where the documentation of every version is built. If Sphinx will at one point of time be chosen as a new rst-builder, it would be needed in the build steps of the Doctrine website.

OskarStark · 2020-02-11T20:19:44Z

Ok I will fix it tomorrow. Yes, it was initially developed for the Symfony docs and we prefer to use twig instead of jinja though... not an issue but more or less our standard, but we can disable the rule ofc 👍🏻

OskarStark · 2020-02-12T06:51:08Z

Done ✅ can you please check again if the rst-parser is complaining about sth? Thanks 🙏

SenseException · 2020-02-12T20:12:35Z

It's looking good so far. The code blocks where you replaced .. code-block:: php with :: will result in missing highlighting and missing line numbers.

This is how the docs currently look like:

And this how it looks like with your changes:

OskarStark · 2020-02-25T07:56:59Z

Hi @SenseException,

thank you for your feedback. I cannot say much about the RST-Parser of doctrine and we had the same "problem" at the symfony-docs repo, to not have highlighting when using ::. We fixed it by telling sphinx "Hey we do mostly PHP stuff, so use it by default" in our config

We can ofc. keep it like before and deactivate the rule or switch to Sphinx, but I don't know which advantages doctrine/rst-parser has at the moment

malarzm · 2020-02-25T07:57:28Z

@OskarStark could you take a look at #613 (comment) ? Do we need to use a default language setting somewhere so the code block won't lose their formatting?

OskarStark · 2020-02-25T08:02:06Z

I just answered 1 minute before 😄

malarzm · 2020-02-25T08:07:21Z

Hah perfect timing :) IIRC RST-Parser was introduced to get rid of sphinx as we were moving out from readthedocs. If we could keep the language setting per code block and it won't bother Symfony ecosystem that'd be great.

OskarStark · 2020-02-25T08:10:45Z

If we could keep the language setting per code block and it won't bother Symfony ecosystem that'd be great.

Sure thing, it will not bother us, its just (because we have a lot of docs), less distracting/noisy to read, I will disable the rule and revert the commit

OskarStark · 2020-02-25T08:14:07Z

Resources/doc/.doctor-rst.yaml

+    versionadded_directive_major_version:
+        major_version: 3
+
+    versionadded_directive_min_version:
+        min_version: '3.0'
+
+    deprecated_directive_major_version:
+        major_version: 3
+
+    deprecated_directive_min_version:
+        min_version: '3.0'


After up merging into 4.x this must be change accordingly. Same for master, if this will be next 5.0, otherwise not.

OskarStark · 2020-02-25T08:14:14Z

I will disable the rule and revert the commit

done

OskarStark · 2020-02-25T08:52:41Z

For the record we use this extension for symfony-docs Sphinx:
https://github.com/fabpot/sphinx-php#sphinx-extensions-for-php-and-symfony

malarzm · 2020-02-26T20:05:12Z

Let's get this merged, thanks a lot @OskarStark!

OskarStark · 2020-02-26T20:11:30Z

Wohoo 🙌 thanks 🥳

SenseException · 2020-02-26T20:51:36Z

Thank you 🌷

OskarStark changed the base branch from master to 3.6.x January 31, 2020 15:02

OskarStark added 2 commits January 31, 2020 16:03

Introduce DOCtor-RST

2ec6b6e

Fix: Use https for xsd

6ba87b3

OskarStark force-pushed the doctor-rst branch from bd774d5 to fbdc1ca Compare January 31, 2020 15:03

OskarStark requested a review from alcaeus January 31, 2020 15:03

malarzm reviewed Feb 1, 2020

View reviewed changes

malarzm approved these changes Feb 1, 2020

View reviewed changes

alcaeus approved these changes Feb 4, 2020

View reviewed changes

alcaeus requested a review from SenseException February 4, 2020 10:18

SenseException requested changes Feb 9, 2020

View reviewed changes

SzymonKaminski mentioned this pull request Feb 17, 2020

Modernize documentation #618

Merged

OskarStark added 2 commits February 25, 2020 09:11

Fix: Use short array syntax

1487bd1

Fix: Add space before self closing XML tag

6064bc2

OskarStark added 9 commits February 25, 2020 09:11

Fix: Remove blank line

f0a38fe

Fix: Sort use statements alphabetically

4b846ee

Fix: use twig instead of jinja

e734fec

Fix: Link

c9f5e2c

Fix: use php-annotations

c5bed93

Fix: Comment

7cd3dad

Fix: Reformat and fix links

7b5dcf1

Use html+jinja again

8d78f19

Disable rule: no_explicit_use_of_code_block_php

9f96537

OskarStark force-pushed the doctor-rst branch from 240fd05 to 9f96537 Compare February 25, 2020 08:13

OskarStark commented Feb 25, 2020

View reviewed changes

formatting

09b1f72

malarzm merged commit 5dd3f0d into doctrine:3.6.x Feb 26, 2020

OskarStark deleted the doctor-rst branch February 27, 2020 07:02

malarzm mentioned this pull request Feb 27, 2020

Fix failures found by DOCtor-RST #620

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce DOCtor-RST #613

Introduce DOCtor-RST #613

OskarStark commented Jan 31, 2020 •

edited

Loading

alcaeus commented Jan 31, 2020

OskarStark commented Jan 31, 2020 •

edited

Loading

malarzm Feb 1, 2020

OskarStark Feb 1, 2020 •

edited

Loading

malarzm Feb 1, 2020 •

edited

Loading

malarzm left a comment

OskarStark commented Feb 1, 2020

alcaeus left a comment

SenseException commented Feb 4, 2020

SenseException left a comment

OskarStark commented Feb 11, 2020

alcaeus commented Feb 11, 2020

SenseException commented Feb 11, 2020

OskarStark commented Feb 11, 2020

SenseException commented Feb 11, 2020

OskarStark commented Feb 11, 2020 via email •

edited

Loading

OskarStark commented Feb 12, 2020

SenseException commented Feb 12, 2020 •

edited

Loading

OskarStark commented Feb 25, 2020

malarzm commented Feb 25, 2020

OskarStark commented Feb 25, 2020

malarzm commented Feb 25, 2020

OskarStark commented Feb 25, 2020

OskarStark Feb 25, 2020

OskarStark commented Feb 25, 2020

OskarStark commented Feb 25, 2020

malarzm commented Feb 26, 2020

OskarStark commented Feb 26, 2020

SenseException commented Feb 26, 2020

Introduce DOCtor-RST #613

Introduce DOCtor-RST #613

Conversation

OskarStark commented Jan 31, 2020 • edited Loading

alcaeus commented Jan 31, 2020

OskarStark commented Jan 31, 2020 • edited Loading

malarzm Feb 1, 2020

Choose a reason for hiding this comment

OskarStark Feb 1, 2020 • edited Loading

Choose a reason for hiding this comment

malarzm Feb 1, 2020 • edited Loading

Choose a reason for hiding this comment

malarzm left a comment

Choose a reason for hiding this comment

OskarStark commented Feb 1, 2020

alcaeus left a comment

Choose a reason for hiding this comment

SenseException commented Feb 4, 2020

SenseException left a comment

Choose a reason for hiding this comment

OskarStark commented Feb 11, 2020

alcaeus commented Feb 11, 2020

SenseException commented Feb 11, 2020

OskarStark commented Feb 11, 2020

SenseException commented Feb 11, 2020

OskarStark commented Feb 11, 2020 via email • edited Loading

OskarStark commented Feb 12, 2020

SenseException commented Feb 12, 2020 • edited Loading

OskarStark commented Feb 25, 2020

malarzm commented Feb 25, 2020

OskarStark commented Feb 25, 2020

malarzm commented Feb 25, 2020

OskarStark commented Feb 25, 2020

OskarStark Feb 25, 2020

Choose a reason for hiding this comment

OskarStark commented Feb 25, 2020

OskarStark commented Feb 25, 2020

malarzm commented Feb 26, 2020

OskarStark commented Feb 26, 2020

SenseException commented Feb 26, 2020

OskarStark commented Jan 31, 2020 •

edited

Loading

OskarStark commented Jan 31, 2020 •

edited

Loading

OskarStark Feb 1, 2020 •

edited

Loading

malarzm Feb 1, 2020 •

edited

Loading

OskarStark commented Feb 11, 2020 via email •

edited

Loading

SenseException commented Feb 12, 2020 •

edited

Loading