search

TYPO3-Documentation / t3SphinxThemeRtd

Please report only issues that concern the rendering of the official TYPO3 docs here. For help and support on TYPO3, please see: https://typo3.org/help/
MIT License
11 stars 7 forks source link

[FEATURE] Add new rendering theme #140

Closed benjaminkott closed 4 years ago

benjaminkott commented 4 years ago

How to Test:

  1. Install 

    yarn install
yarn build

    This will render the "How to Document Guide" as reference. If you want to test a different documentation, simply provide the path.

    # full build
yarn build --source=..\t3SphinxThemeRtdDemoDocs

# just render
yarn render --source=..\t3SphinxThemeRtdDemoDocs

  2. Start HTTP-Server

    yarn serve

  3. Validate Open Browser on the Served Address and check if everything is working

Testing

Each change to the theme will trigger a GitHub action build, that will provide an artifact of a rendered documentation of https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument. See: https://github.com/benjaminkott/typo3-sphinx-theme/actions

  1. image

  2. image

Fixes:

benjaminkott commented 4 years ago

FYI: @marble @DanielSiepmann @sypets I could start working early on the new theme, added a draft pr so you can follow the development. As soon as I reach a "review" worthy state, I´ll let you know.

marble commented 4 years ago

@benjaminkott Fine, thank you, I'll keep watching this and give it a - local - try. cc @DanielSiepmann cc @sypets

benjaminkott commented 4 years ago

@marble added a simple workflow that is rendering the demo docs included in this repository. You can check them currently in my branch:

https://github.com/benjaminkott/typo3-sphinx-theme/commits/task/add-universe-bar

See Example run: https://github.com/benjaminkott/typo3-sphinx-theme/commit/7d3fa6308bd9b8932e6b6c410959e69fbd32cb3b/checks?check_suite_id=348642289

image

cc: @DanielSiepmann @sypets

gilbertsoft commented 4 years ago

Looks great! Nice job Benji!

marble commented 4 years ago

One more: How to provide help to the readers?

Readers often complain about the documentation and don't understand that they can contribute themselves. Some don't want to understand that, but - well... So there is the idea to have a link on each page that directs readers to a landing page in "Writing Documentation".

How and where would we put that?

My opinion: I would leave the beginning of the page exactly as it is now. And the button is fine, as we'll soon have there: "Edit on GitHub", "Edit on BitBucket", "Edit on GitLab". For me the footer seems the right place. Maybe we can have a "prominent" link there, that's sticking out a bit. Supported by an icon? cc → @sypets grafik

(No more comments by me for now.)

benjaminkott commented 4 years ago

@marble thx for checking the rendering. I am aware of the link color but adapted it, for now, to be consistent for most of the platforms. As mentioned I will discuss this with the design team on their sprint in the TYPO3 Office end of January. To have an agreement about the colors and adapt it afterward on all Platforms.

I will check the styling last styling issues later and fix them.

Also will check the job file, which should already now be more minimal now. (Slowly getting how everything works). Maybe we also should add more tests and example renderings in the future?

For the Contributing Part, I've found https://github.com/TYPO3-Documentation/t3SphinxThemeRtd/issues/120 that has more or less the same goal. I would take care of this separately in a dedicated patchset.

There were also tickets about adding additional information to the footer. For now, we have a framework we can then extend with this information over time, and it should be more easy to test and contribute then.

benjaminkott commented 4 years ago

@marble

I could fix the tables and inline-buttons, they should now be fine.

For the conval i am lacking examples in the "How to Document Guide", i´ve checked the sphinx rendering for reference. I fixed some minor styling issues but i would keep the "blue" for now. It is the color we use to provide information that makes sense for me to also use them here. Also the highlights within the conval are currently matching out code-highlights, I corrected font-size, and coloring of methods, so there is a visual difference in the stack.

image

I would personally go with this state now, as long as there are no major bugs anymore.

benjaminkott commented 4 years ago

@marble the math ajax got missing along the way while removing unwanted assets- missed that one. I am not unsetting the files directly, means if plugins provide assets they will be loaded.

Still am not sure about the tables. Checked it in Chrome, Edge and Firefox after I applied the changes. You are sure you had the latest changes in this pr? Change was applied here: https://github.com/TYPO3-Documentation/t3SphinxThemeRtd/pull/140/commits/cb92f2c5dd61a74f8bc31d4bec72ab0316e92241

image

marble commented 4 years ago

You are sure you had the latest changes in this pr?

@benjaminkott You are right, I must have done something wrong, as tables are looking perfect now. Great, it's almost done!

benjaminkott commented 4 years ago

@marble added more styling for blockquotes

image

marble commented 4 years ago

Looks good. How about one of these characters as indicator?: ” or „ or ❝ or ❞ or ❠ ?

benjaminkott commented 4 years ago

@marble Sure, why not - adapted the indicator

image

marble commented 4 years ago

@benjaminkott Does the 'ajaxversions' call work for you? How do you test that? Example uri would be https://docs.typo3.org/services/ajaxversions.php?url=https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/

benjaminkott commented 4 years ago

@marble there are basically 3 ways:

  1. I've checked the response and inserted it manually in the markup.

image

image

  1. I've faked the return value during testing and injected the markup directly.

  2. I've added a static route during development that was used instead of the production url during testing.

marble commented 4 years ago

@benjaminkott ① Yes, I did the same and inserted that manually. That's looking alright. ② Additionally I faked the request which showed a "200 ok" in the devtools network pane but didn't show up on the page. But I didn't investigate that further because I first wanted to ask. ③ BTW: More asking you, for my learning: If we wanted to be really "pingelig", should that be <dd>No data available.</dd>. But I agree, that <p>tag looks nicer.

Summary: ATM I'm not sure the Ajax-data really shows up

benjaminkott commented 4 years ago

Did not change it really only moved the position. In general I am also not so happy with the markup provided by the Ajax response. But did not want to touch it in this run. Would opt for opening an issue for after the rollout. Because we need to change the behavior on both ends.