#1731 Docs for 20.0 release #1754

raman-m · 2023-10-24T20:14:44Z

Fixes #1731

Unable to generate documentation on ReadTheDocs #1731

This is the major update of the documentation for the current 20.0 release.

Proposed Changes

Reviewed all features, pages in .rst files
Updated links & features to meet requirements of 20.0 release
Updated README.md which looks better and modern now
Reviewed development process aka Release Process
Added Future subsections to say about team plans

I guess, most interesting things to look at are:

releaseprocess.rst
Future subsections: git grep 'Future' release/20.0-docs

Review doc. Update by links. Add labels.

…are links

…ution" section

…lders & Future sections

… subsection

…tion

raman-m · 2023-10-24T20:17:12Z

@ggnaegi FYI
The Coveralls.io badge will be hidden on README page until we fix this. 😋

Do you approve this? Something else?

ggnaegi · 2023-10-24T22:36:15Z

@ggnaegi FYI
The Coveralls.io badge will be hidden on README page until we fix this. 😋

Do you approve this? Something else?

Yes, until we introduce sonarqube 😊

raman-m · 2023-10-25T07:04:28Z

@ggnaegi Do you approve?
We're very close to releasing v 20.0.1 with this docs.
As a rest of work, I need to add make.bash to have ability to build docs on Linux machines. Current make.bat allows to build docs on Windows machine only.

ggnaegi · 2023-10-25T07:11:08Z

@ggnaegi Do you approve?
We're very close to releasing v 20.0.1 with this docs.
As a rest of work, I need to add make.bash to have ability to build docs on Linux machines. Current make.bat allows to build docs on Windows machine only.

@raman-m Sounds good to me. Why "-" instead of "^" ?

raman-m · 2023-10-25T07:52:28Z

@ggnaegi commented
Sounds good to me. Why "-" instead of "^" ?

= for sections
- for subsections
^ for subsubsections

All features have been defined as sections with =, and some pages had the next level ^ (subsubsections), which is wrong because the next sublevel after sections is - (subsections).

More here: reST Sections

ggnaegi · 2023-10-25T08:01:12Z

Ok, reviewing the docs :-)

I would be up for the GraphQL bit, but with https://github.com/ChilliCream/graphql-platform, not graphql.net.

I have some experience with HotChocolate, since I implemented GraphQL for a customer.

this .net server is imho better and Michael (the owner) is a member of the GraphQL Technical Steering Committee.

But that's my opinion.

ggnaegi

Great job! I have written two comments, but we should send a positive message to the contributors.

ggnaegi · 2023-10-25T08:04:13Z

docs/features/qualityofservice.rst


-You must set a number greater than 0 against ExceptionsAllowedBeforeBreaking for this rule to be implemented. Duration of break means the circuit breaker will stay open for 1 second after it is tripped.
-TimeoutValue means if a request takes more than 5 seconds it will automatically be timed out. 
+You must set a number greater than ``0`` against **ExceptionsAllowedBeforeBreaking** for this rule to be implemented.


Here I would mention that the functionality is not working at the minute (see ticket).

If we have a bug in backlog, it doesn't mean we have to remove docs, right?
Make sense?

Or, would you like to mention this bug in docs?
Won't it be strange?

I have an idea to mark this feature by special label and redirect users to look at current issues? Souds good? Sounds like a fix of this code review issue?
For example we have label for Websockets feature.

Yes, great idea!

I found it! It is #1550

@ggnaegi I've added special QoS label, and added the reference to QoS footnote in the doc
Fixed in 88fbd1d

ggnaegi · 2023-10-25T08:09:45Z

docs/building/releaseprocess.rst

-All NuGet package builds & releases are done with CircleCI `here <https://circleci.com/gh/ThreeMammals>_` and all releases are done from `here <https://ci.appveyor.com/project/TomPallister/ocelot-ayj4w>_`.
+All NuGet package builds and releases are done with CircleCI, see `Pipelines - ThreeMammals/Ocelot <https://circleci.com/gh/ThreeMammals/Ocelot/>`_.
+
+Only Tom Pallister (owner) and Ocelot Core Team members (maintainers) can merge releases into **main** at the moment.


This is a very negative way of explaining things. I wouldn't tell the contributors about the organizational details, and instead of writing "Do not mention Tom", I would use "Please, mention Raman".

Good point! We need to be more pleasant maintainers. 🤣
I would prefer to replace Do not mention Tom line by another phrase: "We do follow this dev and release process... bla-bla-bla"

As Tom wrote a lot in docs, I would say If you need to do something which we won't do, please help yourself! 🤣

And, relevant version:
If you reference Tom in issues to help, who is not going to reply to you, please help yourself! 🤣

✔️ Fixed in f9f6d8d
Are we pleasant now, @ggnaegi ?

raman-m · 2023-10-25T08:46:50Z

@ggnaegi commented
I would be up for the GraphQL bit, but with https://github.com/ChilliCream/graphql-platform, not graphql.net.

I am not a fun to integrate custom libraries, except direct references to official libs.
Let's discuss GraphQl later, plz!

ggnaegi · 2023-10-25T09:44:25Z

@ggnaegi commented
I would be up for the GraphQL bit, but with https://github.com/ChilliCream/graphql-platform, not graphql.net.

I am not a fun to integrate custom libraries, except direct references to official libs.
Let's discuss GraphQl later, plz!

Mmh. Graphql.NET is not the official implementation by the way. There is no official implementation.

raman-m · 2023-10-25T10:59:45Z

@ggnaegi left a code review comment:
Great job!

Thanks!

I have written two comments, but we should send a positive message to the contributors.

I've fixed issues! Please, approve, if no other issues.

raman-m · 2023-10-25T11:01:25Z

@RaynaldM Hey, Ray!
One more approval please!

ggnaegi

Ok for me, thanks!

raman-m · 2023-10-26T06:44:18Z

@RaynaldM Good morning, France! 😊

Documentation release 20.0.1 -------------------------------- Guillaume Gnaegi (1): #1731 Read the Docs configuration file v2 (#1733) Raman Maksimchuk (1): #1731 Docs for 20.0 release (#1754) raman-m (2): Prepare for the 20.0.1 release Trigger new build...

* Update README.md Review doc. Update by links. Add labels. * Update readme.md: Review doc. Update links * Update building.rst: Review doc * Update overview.rst * Update tests.rst: Review doc. Update links * Update releaseprocess.rst: Update development process * Update bigpicture.rst: Copy Welcoming from README * Update contributing.rst: Add discussions and dev process refs * Update gettingstarted.rst * Update gotchas.rst: Write IIS gotchas * Update notsupported.rst: Add sections. Use more links * Update administration.rst: Review doc. Fix markup. More links * Update authentication.rst: Review doc. Add more links * Update authorization.rst: review. Add "Authorization Middleware" section * Update caching.rst: Review markup. More links * Update claimstransformation.rst: Review doc. Update markdown. Middleware links * Correct spelling error in dev docs * Update configuration.rst: Review the doc. Rewrite "SSL Errors" section * Update delegatinghandlers.rst: Review. More links. Add "Order of Execution" section * Update dependencyinjection.rst: Review the doc. Fix markdown * Update errorcodes.rst: Review. Add "Design" section * Update graphql.rst: Review. Add "Future" section * Update headerstransformation.rst: Review. More links. Rewrite Placeholders & Future sections * Update headerstransformation.rst: Add "Global Headers Transformation" subsection * Update kubernetes.rst: Review. Links. Add K8s logo * Update kubernetes.rst: Add link to the parent feature * Update loadbalancer.rst: Fix markdown. More links * Update logging.rst: More links. Rewrite "Warning" section * Update methodtransformation.rst * Update middlewareinjection.rst: Review. Check links. Add "Future" section * Update qualityofservice.rst: Review markdown * Update ratelimiting.rst: Review. Markdown. Add "Future" section * Update requestaggregation.rst: Review. Fix markdown * Update requestid.rst: Review markdown * Update routing.rst: Review markdown. Simplify code blocks * Update servicediscovery.rst: Review markdown * Update servicefabric.rst: Review markdown * Update tracing.rst: Review markdown. More links * Update websockets.rst: Complete rewrite * Update README.md: Hide Coverage badge. More footnotes * Update README.md: Add "Service Discovery" footnote * Update index.rst: Arrange features. More instructions * Update releaseprocess.rst: Be more pleasant * Update qualityofservice.rst: Add QoS label and footnote * Fix Sphinx build errors & warning. Fix typos * Add bash script * Order feature names ascending * Sync & update scripts

raman-m added 30 commits October 20, 2023 16:53

Update README.md

73c76ae

Review doc. Update by links. Add labels.

Update readme.md: Review doc. Update links

8f0c483

Update building.rst: Review doc

c435321

Update overview.rst

b274aee

Update tests.rst: Review doc. Update links

08fd18d

Update releaseprocess.rst: Update development process

44781a8

Update bigpicture.rst: Copy Welcoming from README

c343cea

Update contributing.rst: Add discussions and dev process refs

ce781b6

Update gettingstarted.rst

7e8a297

Update gotchas.rst: Write IIS gotchas

ee75d9b

Update notsupported.rst: Add sections. Use more links

a45d261

Update administration.rst: Review doc. Fix markup. More links

231f057

Update authentication.rst: Review doc. Add more links

5398254

Update authorization.rst: review. Add "Authorization Middleware" section

b67eb85

Update caching.rst: Review markup. More links

d6e4af6

Update claimstransformation.rst: Review doc. Update markdown. Middlew…

5040761

…are links

Correct spelling error in dev docs

ef5db57

Update configuration.rst: Review the doc. Rewrite "SSL Errors" section

74c5ded

Update delegatinghandlers.rst: Review. More links. Add "Order of Exec…

a4c527b

…ution" section

Update dependencyinjection.rst: Review the doc. Fix markdown

155f2aa

Update errorcodes.rst: Review. Add "Design" section

39d1ca8

Update graphql.rst: Review. Add "Future" section

1ecfd2e

Update headerstransformation.rst: Review. More links. Rewrite Placeho…

33e258a

…lders & Future sections

Update headerstransformation.rst: Add "Global Headers Transformation"…

2a22b26

… subsection

Update kubernetes.rst: Review. Links. Add K8s logo

5e358ee

Update kubernetes.rst: Add link to the parent feature

75f3baa

Update loadbalancer.rst: Fix markdown. More links

f06bf4e

Update logging.rst: More links. Rewrite "Warning" section

f42665a

Update methodtransformation.rst

07af9e4

Update middlewareinjection.rst: Review. Check links. Add "Future" sec…

a25541d

…tion

raman-m self-assigned this Oct 24, 2023

raman-m added documentation Needs a documentation update release Pre/Release (minor, major) labels Oct 24, 2023

raman-m requested a review from RaynaldM October 24, 2023 20:16

ggnaegi approved these changes Oct 25, 2023

View reviewed changes

Update index.rst: Arrange features. More instructions

c8afba9

Update releaseprocess.rst: Be more pleasant

f9f6d8d

Update qualityofservice.rst: Add QoS label and footnote

88fbd1d

raman-m requested a review from ggnaegi October 25, 2023 11:00

raman-m mentioned this pull request Oct 25, 2023

Documentation release 20.0.1 #1755

Merged

ggnaegi approved these changes Oct 25, 2023

View reviewed changes

raman-m added 2 commits October 25, 2023 20:58

Fix Sphinx build errors & warning. Fix typos

f206bae

Add bash script

345554a

raman-m added 2 commits October 26, 2023 13:58

Order feature names ascending

d5b09c3

Sync & update scripts

8dab4ef

raman-m merged commit 640b005 into release/20.0 Oct 26, 2023
2 checks passed

raman-m deleted the release/20.0-docs branch October 26, 2023 11:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

#1731 Docs for 20.0 release #1754

#1731 Docs for 20.0 release #1754

raman-m commented Oct 24, 2023 •

edited

Loading

raman-m commented Oct 24, 2023 •

edited

Loading

ggnaegi commented Oct 24, 2023

raman-m commented Oct 25, 2023

ggnaegi commented Oct 25, 2023

raman-m commented Oct 25, 2023

ggnaegi commented Oct 25, 2023

ggnaegi left a comment •

edited

Loading

ggnaegi Oct 25, 2023

raman-m Oct 25, 2023

raman-m Oct 25, 2023

raman-m Oct 25, 2023

raman-m Oct 25, 2023

ggnaegi Oct 25, 2023

raman-m Oct 25, 2023 •

edited

Loading

ggnaegi Oct 25, 2023

raman-m Oct 25, 2023

raman-m Oct 25, 2023 •

edited

Loading

raman-m Oct 25, 2023 •

edited

Loading

raman-m commented Oct 25, 2023

ggnaegi commented Oct 25, 2023

raman-m commented Oct 25, 2023

raman-m commented Oct 25, 2023

ggnaegi left a comment

raman-m commented Oct 26, 2023

#1731 Docs for 20.0 release #1754

#1731 Docs for 20.0 release #1754

Conversation

raman-m commented Oct 24, 2023 • edited Loading

Fixes #1731

Proposed Changes

raman-m commented Oct 24, 2023 • edited Loading

ggnaegi commented Oct 24, 2023

raman-m commented Oct 25, 2023

ggnaegi commented Oct 25, 2023

raman-m commented Oct 25, 2023

ggnaegi commented Oct 25, 2023

ggnaegi left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raman-m Oct 25, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raman-m Oct 25, 2023 • edited Loading

Choose a reason for hiding this comment

raman-m Oct 25, 2023 • edited Loading

Choose a reason for hiding this comment

raman-m commented Oct 25, 2023

ggnaegi commented Oct 25, 2023

raman-m commented Oct 25, 2023

raman-m commented Oct 25, 2023

ggnaegi left a comment

Choose a reason for hiding this comment

raman-m commented Oct 26, 2023

raman-m commented Oct 24, 2023 •

edited

Loading

raman-m commented Oct 24, 2023 •

edited

Loading

ggnaegi left a comment •

edited

Loading

raman-m Oct 25, 2023 •

edited

Loading

raman-m Oct 25, 2023 •

edited

Loading

raman-m Oct 25, 2023 •

edited

Loading