search

Azure / azure-sdk-for-python

This repository is for active development of the Azure SDK for Python. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/python/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-python.
MIT License
4.64k stars 2.84k forks source link

[azure-ai-ml] Docs CI issue #30774

Open danieljurek opened 1 year ago

danieljurek commented 1 year ago

Doc comments have errors which are causing the docs CI build to fail. Docs build has been pinned to 1.7.2 until this can be resolved.

To fix:

  1. Fix problems in code
  2. Release an updated package
  3. Remove package from $PackageExclusions in Langauge-Settings.ps1

Failing build: https://apidrop.visualstudio.com/Content%20CI/_build/results?buildId=367844&view=logs&j=fd490c07-0b22-5182-fac9-6d67fe1e939b&t=25941825-f6be-5547-87e7-b619f675754d&l=295881

Observed errors: 

<Matched Warning>: C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\entities\_compute\aml_compute.py:docstring of azure.ai.ml.entities._compute.aml_compute.AmlCompute:1: WARNING: Block quote ends without a blank line; unexpected unindent.
##[error]Run-WithWarningFilter : <Matched Error>: 
C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\entities\_credentials.py:docstring of 
azure.ai.ml.entities._credentials.AccessKeyConfiguration:1: ERROR: Error in "literalinclude" directive:
At D:\a\_work\1\s\python\build.ps1:146 char:13
+             Run-WithWarningFilter -Command $sphinxBuildPath -Paramete ...
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Run-WithWarningFilter

WARNING: <Plain Warning>: invalid option block.
WARNING: <Plain Warning>: System.Management.Automation.RemoteException
WARNING: <Plain Warning>: .. literalinclude:: ../samples/ml_samples_sweep_configurations.py
WARNING: <Plain Warning>:     :start-after: [START configure_sweep_job_uniform]
WARNING: <Plain Warning>:     :end-before: [END configure_sweep_job_uniform]
WARNING: <Plain Warning>:     :language: python
WARNING: <Plain Warning>:     :dedent: 8
WARNING: <Plain Warning>:     :caption: Configuring Uniform distributions for learning rates and momentum
WARNING: <Plain Warning>:     during a hyperparameter sweep on a Command job.

<Matched Warning>: C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\entities\_job\sweep\early_termination_policy.py:docstring of azure.ai.ml.entities._job.sweep.early_termination_policy.BanditPolicy:24: WARNING: Field list ends without a blank line; unexpected unindent.
##[error]Run-WithWarningFilter : <Matched Error>: C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\ent
ities\_job\sweep\early_termination_policy.py:docstring of 
azure.ai.ml.entities._job.sweep.early_termination_policy.BanditPolicy:5: ERROR: Error in "literalinclude" directive:
At D:\a\_work\1\s\python\build.ps1:146 char:13
+             Run-WithWarningFilter -Command $sphinxBuildPath -Paramete ...
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Run-WithWarningFilter

WARNING: <Plain Warning>: invalid option block.
WARNING: <Plain Warning>: System.Management.Automation.RemoteException
WARNING: <Plain Warning>: .. literalinclude:: ../samples/ml_samples_sweep_configurations.py
WARNING: <Plain Warning>:     :start-after: [START configure_sweep_job_truncation_selection_policy]
WARNING: <Plain Warning>:     :end-before: [END configure_sweep_job_truncation_selection_policy]
WARNING: <Plain Warning>:     :language: python
WARNING: <Plain Warning>:     :dedent: 8
WARNING: <Plain Warning>:     :caption: Configuring an early termination policy for a hyperparameter sweep job
WARNING: <Plain Warning>:     using TruncationStoppingPolicy
<Matched Warning>: C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\entities\_job\sweep\search_space.py:docstring of azure.ai.ml.entities._job.sweep.search_space.Uniform:1: WARNING: duplicate object description of azure.ai.ml.entities._job.sweep.search_space.Uniform, other instance in azure.ai.ml.entities, use :noindex: for one of them
##[error]Run-WithWarningFilter : <Matched Error>: C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\ent
ities\_job\sweep\early_termination_policy.py:docstring of 
azure.ai.ml.entities._job.sweep.early_termination_policy.BanditPolicy:3: ERROR: Error in "literalinclude" directive:
At D:\a\_work\1\s\python\build.ps1:146 char:13
+             Run-WithWarningFilter -Command $sphinxBuildPath -Paramete ...
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Run-WithWarningFilter

WARNING: <Plain Warning>: invalid option block.
WARNING: <Plain Warning>: System.Management.Automation.RemoteException
WARNING: <Plain Warning>: .. literalinclude:: ../samples/ml_samples_sweep_configurations.py
WARNING: <Plain Warning>:     :start-after: [START configure_sweep_job_uniform]
WARNING: <Plain Warning>:     :end-before: [END configure_sweep_job_uniform]
WARNING: <Plain Warning>:     :language: python
WARNING: <Plain Warning>:     :dedent: 8
WARNING: <Plain Warning>:     :caption: Configuring Uniform distributions for learning rates and momentum
WARNING: <Plain Warning>:     during a hyperparameter sweep on a Command job.
looking for now-outdated files... none found
pickling environment... done
<Matched Warning>: D:\a\_work\1\s\dist_temp\205\azure-ai-ml-1.8.0\doc\azure.rst: WARNING: document isn't included in any toctree
<Matched Warning>: D:\a\_work\1\s\dist_temp\205\azure-ai-ml-1.8.0\doc\azure.ai.rst: WARNING: document isn't included in any toctree
checking consistency... done
preparing documents... done
mccoyp commented 1 year ago

Hi @diondrapeck, I think the error here is coming from an incorrect sample file location in the docstring (introduced in https://github.com/Azure/azure-sdk-for-python/pull/30434). For example, in the second error listed, we're referencing a sample file from azure.ai.ml.entities._job.sweep.early_termination_policy -- since samples is at the root of the package, I think we'd need to replace

literalinclude:: ../samples/ml_samples_sweep_configurations.py

with

literalinclude:: ../../../../../../samples/ml_samples_sweep_configurations.py

The file is nested pretty deep, so I may be off by a .. 😅 You should be able to double-check by locally generating sphinx docs on the azure-ai-ml package, since I would think you'll either get an error or incorrectly rendered snippet if the file path is invalid. If you're on tox 4, you can run tox run -e sphinx --root . from the root of the package; you can also just run sphinx directly if you prefer 🙂

EDIT: actually, looking at other packages, I don't think that's the issue... it's probably something more subtle. Feel free to ignore me!

diondrapeck commented 1 year ago
: C:\hostedtoolcache\windows\Python\3.11.3\x64\Lib\site-packages\azure\ai\ml\entities\_job\sweep\search_space.py:docstring of azure.ai.ml.entities._job.sweep.search_space.Uniform:1: WARNING: duplicate object description of azure.ai.ml.entities._job.sweep.search_space.Uniform, other instance in azure.ai.ml.entities, use :noindex: for one of them

Thanks for this, @mccoyp. Sorry I didn't see it - GitHub never emailed me the notification :|

I think you might be right here actually. I didn't adjust the paths here. It works for something like MLClient because it's only one folder removed. I'm pretty sure the path should be relative to the file it's cited in. I'm going to update them.

diondrapeck commented 1 year ago

PR: https://github.com/Azure/azure-sdk-for-python/pull/31137

diondrapeck commented 1 year ago

image

mccoyp commented 1 year ago

@diondrapeck is that build with the changes from #31137?

@danieljurek is there any way we can test the docs build before releasing a new package, to make sure this fixes the issue?

diondrapeck commented 1 year ago

Yep, @mccoyp it's that build.

danieljurek commented 1 year ago

@mccoyp -- Yes, this can be accomplished through daily docs but the changes to Language-Settings.ps1 have to be in place.

Looks like this package is still excluded from onboarding: https://github.com/Azure/azure-sdk-for-python/blob/main/eng/scripts/Language-Settings.ps1#L307C63-L307C63 ... Re-opening to track adding this back to onboarding.