Unable to generate documentation on ReadTheDocs #1731

ggnaegi · 2023-10-15T09:25:26Z

Expected Behavior / New Feature

We would expect the documentation to be generated on a regular basis, to avoid misunderstandings. 😸

Actual Behavior / Motivation for New Feature

The documentation generation process fails at the moment:
Build #22151302 | Ocelot | Read the Docs

The reason is that Read the Docs has stopped supporting docs generation without the .readthedocs.yaml config file:
Migrate your project to .readthedocs.yaml configuration file v2 — Read the Docs Blog

Solution

A simple solution is given in the PR. By adding a config file to the solution's root folder the docs are generated.
See demo account by @ggnaegi: https://ocelot-test.readthedocs.io/en/bug-fix_documentation_generation/

The text was updated successfully, but these errors were encountered:

raman-m · 2023-10-15T14:00:57Z

Thanks for creation! 👍

+ Accepted

Do we build main branch commits or develop one too?
https://readthedocs.org/projects/ocelot/versions/
For now I cannot get the difference between stable and latest version...

ggnaegi · 2023-10-15T14:26:11Z

@raman-m stable are the releases and latest is main. So, we should add the yaml to main as well.
e.g. stable
git fetch origin --force --prune --prune-tags --depth 50 ebe70fd784b7c928fad4c1ca3be2b7e6892f0680 -> 19.0.3

* fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

* 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 · 2023-10-26T11:16:28Z

@ggnaegi The hotfix has been delivered to release/20.0 branch, see commit 640b005
The release PR is #1755 .
Would you like to wait until the release done and close the ticket, or could we attach this issue to #1755 ?

ggnaegi · 2023-10-26T11:19:41Z

@raman-m Do what suits you best.

raman-m · 2023-10-26T11:40:25Z

@raman-m Do what suits you best.

It is better to link issue to the PR, and it'll be closed automatically.
PRs to release branches don't close issues because there are no protection rules defined for release branches.
We have two protected branches: main and develop

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...

raman-m · 2023-10-27T17:25:36Z

Released in 20.0.1
Commit: d3a623e

) * fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

* 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

) * fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

@ibnuda

* feature written, tests passed * actualy passes almost all the test. * resolve conflict, hopefully. * please. * let it cook. * uses constants instead of string for version policies. * conflict res * swapped downstream method and version. * #1731 Read the Docs configuration file v2 (#1733) * fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com> * * When using the QoS option "ExceptionsAllowedBeforeBreaking" the circuit breaker never opens the circuit. * merge issue, PortFinder * some code improvements, using httpresponsemessage status codes as a base for circuit breaker * Adding more unit tests, and trying to mitigate the test issues with the method "GivenThereIsAPossiblyBrokenServiceRunningOn" * fixing some test issues * setting timeout value to 5000 to avoid side effects * again timing issues * timing issues again * ok, first one ok * Revert "ok, first one ok" This reverts commit 2e4a673. * inline method * putting back logging for http request exception * removing logger configuration, back to default * adding a bit more tests to check the policy wrap * Removing TimeoutStrategy from parameters, it's set by default to pessimistic, at least one policy will be returned, so using First() in circuit breaker and removing the branch Policy == null from delegating handler. * Fix StyleCop warnings * Format parameters * Sort usings * since we might have two policies wrapped, timeout and circuit breaker, we can't use the name CircuitBreaker for polly qos provider, it's not right. Using PollyPolicyWrapper and AsnycPollyPolicy instead. * modifying circuit breaker delegating handler name, usin Polly policies instead * renaming CircuitBreakerFactory to PolicyWrapperFactory in tests * DRY for FileConfiguration, using FileConfigurationFactory * Add copy constructor * Refactor setup * Use expression body for method * Fix acceptance test * IDE1006 Naming rule violation: These words must begin with upper case characters * CA1816 Change ReturnsErrorTests.Dispose() to call GC.SuppressFinalize(object) * Sort usings * Use expression body for method * Return back named arguments --------- Co-authored-by: raman-m <dotnet044@gmail.com> * feature written, tests passed * actualy passes almost all the test. * resolve conflict, hopefully. * missed this one. * please. * come on... * let it build. * let it cook. * copied from main branch. * conflict res * resolving conflicts. * another attempt. * lf * re-incorporate downstream version policy. * renamed the version policies and added acceptance tests. * trust the dotnet dev cert. * accepts cert from dotnet. * Fix compiling errors * Refactor tests * a bit of code cleanup, removing some usings * a bit more cleanup in fileroute * try and error with the tests * "Yahoo!...", said @ibnuda :) * FileRoute: let it go... Binary copy! :LoL: * FileRoute: let it cook... Re-add sweet props * `dotnet dev-certs` for the `build` job * Recover `kubernetes.rst` * docs/make.bat original version * OcelotBuilderExtensions * original src/Ocelot.Provider.Polly/v7/PollyPolicyWrapper.cs * `IVersionPolicyCreator` XML docs * Code review by @raman-m (part 1) * RequestMapper : care about diff * Code review by @raman-m (part 2) * Fix Should_return_OK_status_and_multiline_indented_json_response_with_json_options_for_custom_builder * Update configuration.rst Add DownstreamVersionPolicy section * Update docs * Rename `DownstreamVersionPolicy` to `DownstreamHttpVersionPolicy` * update docs after prop renaming * Sort props --------- Co-authored-by: Guillaume Gnaegi <58469901+ggnaegi@users.noreply.github.com> Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

@ibnuda

* actualy passes almost all the test. * resolve conflict, hopefully. * please. * let it cook. * uses constants instead of string for version policies. * conflict res * swapped downstream method and version. * #1731 Read the Docs configuration file v2 (#1733) * fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com> * * When using the QoS option "ExceptionsAllowedBeforeBreaking" the circuit breaker never opens the circuit. * merge issue, PortFinder * some code improvements, using httpresponsemessage status codes as a base for circuit breaker * Adding more unit tests, and trying to mitigate the test issues with the method "GivenThereIsAPossiblyBrokenServiceRunningOn" * fixing some test issues * setting timeout value to 5000 to avoid side effects * again timing issues * timing issues again * ok, first one ok * Revert "ok, first one ok" This reverts commit 2e4a673. * inline method * putting back logging for http request exception * removing logger configuration, back to default * adding a bit more tests to check the policy wrap * Removing TimeoutStrategy from parameters, it's set by default to pessimistic, at least one policy will be returned, so using First() in circuit breaker and removing the branch Policy == null from delegating handler. * Fix StyleCop warnings * Format parameters * Sort usings * since we might have two policies wrapped, timeout and circuit breaker, we can't use the name CircuitBreaker for polly qos provider, it's not right. Using PollyPolicyWrapper and AsnycPollyPolicy instead. * modifying circuit breaker delegating handler name, usin Polly policies instead * renaming CircuitBreakerFactory to PolicyWrapperFactory in tests * DRY for FileConfiguration, using FileConfigurationFactory * Add copy constructor * Refactor setup * Use expression body for method * Fix acceptance test * IDE1006 Naming rule violation: These words must begin with upper case characters * CA1816 Change ReturnsErrorTests.Dispose() to call GC.SuppressFinalize(object) * Sort usings * Use expression body for method * Return back named arguments --------- Co-authored-by: raman-m <dotnet044@gmail.com> * feature written, tests passed * actualy passes almost all the test. * resolve conflict, hopefully. * missed this one. * please. * come on... * let it build. * let it cook. * copied from main branch. * conflict res * resolving conflicts. * another attempt. * lf * re-incorporate downstream version policy. * renamed the version policies and added acceptance tests. * trust the dotnet dev cert. * accepts cert from dotnet. * Fix compiling errors * Refactor tests * a bit of code cleanup, removing some usings * a bit more cleanup in fileroute * try and error with the tests * "Yahoo!...", said @ibnuda :) * FileRoute: let it go... Binary copy! :LoL: * FileRoute: let it cook... Re-add sweet props * `dotnet dev-certs` for the `build` job * Recover `kubernetes.rst` * docs/make.bat original version * OcelotBuilderExtensions * original src/Ocelot.Provider.Polly/v7/PollyPolicyWrapper.cs * `IVersionPolicyCreator` XML docs * Code review by @raman-m (part 1) * RequestMapper : care about diff * Code review by @raman-m (part 2) * Fix Should_return_OK_status_and_multiline_indented_json_response_with_json_options_for_custom_builder * Update configuration.rst Add DownstreamVersionPolicy section * Update docs * Rename `DownstreamVersionPolicy` to `DownstreamHttpVersionPolicy` * update docs after prop renaming * Sort props --------- Co-authored-by: Guillaume Gnaegi <58469901+ggnaegi@users.noreply.github.com> Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

@ibnuda

* feature written, tests passed * actualy passes almost all the test. * resolve conflict, hopefully. * please. * let it cook. * uses constants instead of string for version policies. * conflict res * swapped downstream method and version. * #1731 Read the Docs configuration file v2 (#1733) * fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com> * * When using the QoS option "ExceptionsAllowedBeforeBreaking" the circuit breaker never opens the circuit. * merge issue, PortFinder * some code improvements, using httpresponsemessage status codes as a base for circuit breaker * Adding more unit tests, and trying to mitigate the test issues with the method "GivenThereIsAPossiblyBrokenServiceRunningOn" * fixing some test issues * setting timeout value to 5000 to avoid side effects * again timing issues * timing issues again * ok, first one ok * Revert "ok, first one ok" This reverts commit 2e4a673. * inline method * putting back logging for http request exception * removing logger configuration, back to default * adding a bit more tests to check the policy wrap * Removing TimeoutStrategy from parameters, it's set by default to pessimistic, at least one policy will be returned, so using First() in circuit breaker and removing the branch Policy == null from delegating handler. * Fix StyleCop warnings * Format parameters * Sort usings * since we might have two policies wrapped, timeout and circuit breaker, we can't use the name CircuitBreaker for polly qos provider, it's not right. Using PollyPolicyWrapper and AsnycPollyPolicy instead. * modifying circuit breaker delegating handler name, usin Polly policies instead * renaming CircuitBreakerFactory to PolicyWrapperFactory in tests * DRY for FileConfiguration, using FileConfigurationFactory * Add copy constructor * Refactor setup * Use expression body for method * Fix acceptance test * IDE1006 Naming rule violation: These words must begin with upper case characters * CA1816 Change ReturnsErrorTests.Dispose() to call GC.SuppressFinalize(object) * Sort usings * Use expression body for method * Return back named arguments --------- Co-authored-by: raman-m <dotnet044@gmail.com> * feature written, tests passed * actualy passes almost all the test. * resolve conflict, hopefully. * missed this one. * please. * come on... * let it build. * let it cook. * copied from main branch. * conflict res * resolving conflicts. * another attempt. * lf * re-incorporate downstream version policy. * renamed the version policies and added acceptance tests. * trust the dotnet dev cert. * accepts cert from dotnet. * Fix compiling errors * Refactor tests * a bit of code cleanup, removing some usings * a bit more cleanup in fileroute * try and error with the tests * "Yahoo!...", said @ibnuda :) * FileRoute: let it go... Binary copy! :LoL: * FileRoute: let it cook... Re-add sweet props * `dotnet dev-certs` for the `build` job * Recover `kubernetes.rst` * docs/make.bat original version * OcelotBuilderExtensions * original src/Ocelot.Provider.Polly/v7/PollyPolicyWrapper.cs * `IVersionPolicyCreator` XML docs * Code review by @raman-m (part 1) * RequestMapper : care about diff * Code review by @raman-m (part 2) * Fix Should_return_OK_status_and_multiline_indented_json_response_with_json_options_for_custom_builder * Update configuration.rst Add DownstreamVersionPolicy section * Update docs * Rename `DownstreamVersionPolicy` to `DownstreamHttpVersionPolicy` * update docs after prop renaming * Sort props --------- Co-authored-by: Guillaume Gnaegi <58469901+ggnaegi@users.noreply.github.com> Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

This was referenced Oct 15, 2023

adding read the docs yaml config file #1732

Closed

#1731 Read the Docs configuration file v2 #1733

Merged

raman-m assigned ggnaegi Oct 15, 2023

raman-m added bug Identified as a potential bug accepted Bug or feature would be accepted as a PR or is being worked on documentation Needs a documentation update labels Oct 15, 2023

raman-m added hotfix Gitflow: Hotfix issue, PR related to hotfix branch and removed bug Identified as a potential bug labels Oct 15, 2023

raman-m linked a pull request Oct 15, 2023 that will close this issue

#1731 Read the Docs configuration file v2 #1733

Merged

raman-m mentioned this issue Oct 24, 2023

#1731 Docs for 20.0 release #1754

Merged

raman-m linked a pull request Oct 24, 2023 that will close this issue

#1731 Docs for 20.0 release #1754

Merged

raman-m added merged Issue has been merged to dev and is waiting for the next release and removed accepted Bug or feature would be accepted as a PR or is being worked on labels Oct 26, 2023

raman-m linked a pull request Oct 26, 2023 that will close this issue

Documentation release 20.0.1 #1755

Merged

raman-m closed this as completed Oct 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unable to generate documentation on ReadTheDocs #1731

Unable to generate documentation on ReadTheDocs #1731

ggnaegi commented Oct 15, 2023 •

edited by raman-m

raman-m commented Oct 15, 2023

ggnaegi commented Oct 15, 2023 •

edited

raman-m commented Oct 26, 2023

ggnaegi commented Oct 26, 2023

raman-m commented Oct 26, 2023 •

edited

raman-m commented Oct 27, 2023

Unable to generate documentation on ReadTheDocs #1731

Unable to generate documentation on ReadTheDocs #1731

Comments

ggnaegi commented Oct 15, 2023 • edited by raman-m

Expected Behavior / New Feature

Actual Behavior / Motivation for New Feature

Solution

raman-m commented Oct 15, 2023

ggnaegi commented Oct 15, 2023 • edited

raman-m commented Oct 26, 2023

ggnaegi commented Oct 26, 2023

raman-m commented Oct 26, 2023 • edited

raman-m commented Oct 27, 2023

ggnaegi commented Oct 15, 2023 •

edited by raman-m

ggnaegi commented Oct 15, 2023 •

edited

raman-m commented Oct 26, 2023 •

edited