Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Unable to generate local doc using Sphinx #16184

Closed
SuperChenSSS opened this issue Jan 15, 2021 · 5 comments
Closed

Unable to generate local doc using Sphinx #16184

SuperChenSSS opened this issue Jan 15, 2021 · 5 comments
Assignees
@scbedd
Labels
Client This issue points to a problem in the data-plane of the library. Cosmos Docs

Comments

@SuperChenSSS
Copy link

  • Package Name: cosmos, Sphinx
  • Package Version: V4
  • Operating System: Ubuntu
  • Python Version: 3.8.5

Describe the bug
I can see doc folder in the repository. I tried to use Sphinx-build tool to generate the doc containing cosmos APIs, but got errors and see the content is blank for cosmos APIs.

To Reproduce
That's the steps I followed:

  1. cd doc/sphinx
  2. sphinx-apidoc -f -e -o ref ../../sdk/cosmos/
  3. make html

Expected behavior
Doc generated with cosmos APIs.

Screenshots
Got errors during make html:
image
image

Also going into the static index.html page, found azure.cosmos API is empty:
image

Additional context
We would like to know:

  1. If the steps are correct to generate API docs?
  2. By reading errors, it seems some contents are missing from the ref folder. How should I avoid these and see actual content in the generated html page?
@ghost ghost added the needs-triage Workflow: This is a new issue that needs to be triaged to the appropriate team. label Jan 15, 2021
@ghost
Copy link

ghost commented Jan 15, 2021

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @southpolesteve, @zfoster

@southpolesteve
Copy link
Contributor

@annatisch @scbedd Can you take a look at this?

@annatisch
Copy link
Member

@scbedd - Is there a tox command that handles local docs generation?

@scbedd
Copy link
Member

scbedd commented Jan 20, 2021

@annatisch absolutely.

@SuperChenSSS to locally generate documentation, please follow the contributing to install tox and tox-monorepo. Once that's done, invoke tox -e sphinx -c ../../eng/tox/tox.inifrom within the package directory that you want to generate documentation for!

@xiangyan99 xiangyan99 added Client This issue points to a problem in the data-plane of the library. Cosmos Docs labels Feb 25, 2021
@ghost ghost removed the needs-triage Workflow: This is a new issue that needs to be triaged to the appropriate team. label Feb 25, 2021
@scbedd
Copy link
Member

scbedd commented Mar 9, 2021

Hey @SuperChenSSS I am going to close this issue. I believe I have addressed your issues above. If you have any further questions feel free to ping me here!

@scbedd scbedd closed this as completed Mar 9, 2021
openapi-sdkautomation bot pushed a commit to AzureSDKAutomation/azure-sdk-for-python that referenced this issue Oct 6, 2021
@JackTn @zhenglaizhang
@leni-msft @najian @raych1 @idear1203 @msyyc @AriZavala2 @PingZhu2232 @markcowl @Mohit-Chakraborty @roslynlu @Alancere @edwin-msft @dochollidayxx @yifan-zhou922 @parvsaxena @hvermis @xuepingd @laxmankumar12 @hjhhh3000vitae @RAY-316 @kangsun-ctrl @brpanask @rebecca337 @xunsun-commits @wanyang7 @soma-ms
CodeGen from PR 16289 in Azure/azure-rest-api-specs
a1d7761 
Dev sql microsoft.sql 2021 05 01 preview release (Azure#16289)

* add base for Microsoft.sql

* Update Readme.md

* update version in swagger example files

* remove ss

* update swagger files

* update readme.md

* add missing json files

* update custom-words.txt to address the spelling check

* remove 201 define in ServerUpdate.json

* Sync sql 2021 05 01 with main branch (Azure#16236)

* Update comment.yml for publish pr (Azure#16166)

* Update comment.yml

* Update comment.yml

* Bump dependencies (Azure#16170)

* bump avocado

* bump mocha

* remove submodule (Azure#16171)

* add azure-resource-manager-schema to servicelinker (Azure#16176)

Co-authored-by: Nan Jiang <naji@microsoft.com>

* Update pr assignment config (Azure#16175)

* [Synapse] - fix scheme for Artifacts and update readme to include KQL scripts for October release (Azure#16035)

* [Synapse] - fix scheme for Notebook, Spark Job definition and SQL script

* Update dataset, linked service and pipeline

* Update release tag for october release

* Correct type of result limit

* Add arguments for SynapseSparkJobActivityTypeProperties

Co-authored-by: Dongwei Wang <dongwwa@microsoft.com>

* fix (Azure#16164)

Merging the change to have accurate Swagger

* Remove requirement of identity field in the request for TURN. (Azure#15966)

* Remove requirement of identity field in the request.

* Update PR

* Address comment

* change api version in readme for sdk release (Azure#16187)

* Add blockchain to latest profile

* Add additional types

* api version change

Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Co-authored-by: Ping Zhu <pizh@Pings-MacBook-Pro.local>

* [Search] Rename types for better SDK code (Azure#16039)

* Rename types for better SDK code

* Rename Speller and Captions search options

* Reorder parameters to have consistency across APIs

* Remove 'SearchIndexer' prefix from projection selectors

Remove 'global' prefix from default flags on custom entities

* Change enum name AdlsGen2->AzureDataLakeStorageGen2

Change property name storageContainer->storageContainerName

* move additional .NET SDK renames to the REST spec

* Revert changes in KnowledgeStore which has GAed

* Revert changes in CustomEntityLookupSkill which has GAed

* Revert changes in SIKSBlobProjectionSelector which has GAed

* Revert changes in SearchIndexerDataSourceType which has GAed

* Rename ignoreResetRequirements->skipIndexerResetRequirementForCache

* fix validStreamingUnits (Azure#16143)

Co-authored-by: Roslyn Lu <roslu@microsoft.com>

* Fix schemas readme files (Azure#16207)

* Fix schemas readme files

* fix ref

* add resourcemanager in module-name (Azure#16206)

* add resourcemanager in module-name

* add go track2 repo in readme.md

* fix

* Minor description update for createorupdate & update slot (Azure#15457)

* add scmMinTlsVersion

* modify description for createorupdate & update slot for all API versions

Co-authored-by: Edwin Diaz <eddiazme@microsoft.com>

* [Hub Generated] Review request for Microsoft.Security to add version preview/2021-08-01-preview (Azure#16096)

* Adds base for updating Microsoft.Security from version stable/2021-07-01 to version 2021-08-01-preview

* Updates readme

* Updates API version in new specs and examples

* First pass at Microsoft.Security/standards for review/preview

* Addressing Round-1 feedback, adding missing descriptions and changing scoping to match ProxyResource type

* First pass for Microsoft.Security\standardComponents

* Changes to fix a typo in an example spec

* Added Microsoft.Security/standardAssignments

* Fix naming convention issue

* Removed types based on Hila's feedback

* Changes to data model for both API calls

* Fix example errors and typos

* Add systemData to Microsoft.Security/standards

* Changes to fix systemData linting

* un-nest systemData fields in examples

* More systemData placement

* Naming convention name to assignments from standardAssignment

* Additional example added

* Changes to address descriptive comments on field types

* Add systemData readOnly

* prettier-fix against examples

* Cleaned types to ref standard v2 common-types entry similar to securityForIoT

* Re-added v2 folder?

* Missed a change here?

* Cleanup of v2 type completely, updated readme.md

* Adds suppression to readme

* Adds suppression to readme

* Change modification to suppress operations linting

Co-authored-by: Adam Holliday <adamho@microsoft.com>

* Yifanzhou/api version change (Azure#16191)

* remove Catalog

* update 2021-05-01-preview

* delete 2021-09-01

* Update readme.md

* Update purviewcatalog.json

* change read-only property (Azure#16209)

Co-authored-by: Parv Saxena <pasaxena@microsoft.com>

* Update account.json - make CollectionReferece type writable (Azure#16208)

* Update account.json

Updating the CollectionReference to be writeable to unblock the customers.

* Update account.json

Need the default set in the client SDK

* Fixed an event name typo in its description. (Azure#16227)

* Introduce new API version for Microsoft.ProviderHub 2021-09-01-preview (Azure#15723)

* Introduce new API version for Microsoft.ProviderHub 2021-09-01-preview

* Add PrivateResourceProviderConfigurations

* Add PrivateRP examples

* Fix enum type.

* Fix enum again

* Prettier

* Fix prettier error

* Add readme.md + prettier

* Fix

* Fix avocado error

* Modify interface

* Fix issue

* Make it private preview

* Remove private RP changes

* Update SKU settings

Co-authored-by: REDMOND\lakshv <lakshv@microsoft.com>
Co-authored-by: He Huang <47040595+hjhhh3000vitae@users.noreply.github.com>

* fluidrelay_readme_config (Azure#16192)

fluidrelay_readme_config

* Add community gallery proxy resource (Azure#16043)

* [Hub Generated] Public private branch 'dev-storagecache-Microsoft.StorageCache-2021-09-01' (Azure#16152)

* Adds base for updating Microsoft.StorageCache from version stable/2021-05-01 to version 2021-09-01

* Updates readme

* Updates API version in new specs and examples

* 2021-09-01 API

* Fix LintDiff

Co-authored-by: rebecca337 <80353400+rebecca337@users.noreply.github.com>
Co-authored-by: Rebecca Dupuis <rdupuis@microsoft.com>

* Fix S360 bugs for swagger FSPG 2020-02-14-preview, 2021-06-01-preview and 2021-06-01 APIs (Azure#15946)

* Changed FSPG RestartParameter.failoverMode from string to enum for API 2021-06-01, 2021-06-01-preview, and 2021-06-15-privatepreview

* Change enum first letter to lower case

* Change to upper case

* Fix S360 bugs for swagger FSPG 2020-02-14-preview, 2021-06-01-preview and 2021-06-01 APIs

* Add email reminder when PR makes changes in Synapse (Azure#16116)

* add email reminder to synapse

* fix for comment

* ServiceBus add batch tag (Azure#16229)

* add code owner to synapse (Azure#16230)

* [Datafactory] Power Query model changes for multiple queries (Azure#16158)

* [Synapse] Add release tag for management SDK Oct. release (Azure#16213)

* update release tag

* fix for avocado

Co-authored-by: Tianen <347142915@qq.com>
Co-authored-by: Zhenglai Zhang <darinzh@microsoft.com>
Co-authored-by: Lei Ni <7233663+leni-msft@users.noreply.github.com>
Co-authored-by: najian <jiangnan8924@gmail.com>
Co-authored-by: Nan Jiang <naji@microsoft.com>
Co-authored-by: Ray Chen <raychen@microsoft.com>
Co-authored-by: Dongwei Wang <bean0idear@163.com>
Co-authored-by: Dongwei Wang <dongwwa@microsoft.com>
Co-authored-by: msyyc <70930885+msyyc@users.noreply.github.com>
Co-authored-by: AriZavala2 <77034370+AriZavala2@users.noreply.github.com>
Co-authored-by: PingZhu2232 <36140352+PingZhu2232@users.noreply.github.com>
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Co-authored-by: Ping Zhu <pizh@Pings-MacBook-Pro.local>
Co-authored-by: Mohit Chakraborty <8271806+Mohit-Chakraborty@users.noreply.github.com>
Co-authored-by: Roslyn Lu <roslyn.lu@gmail.com>
Co-authored-by: Roslyn Lu <roslu@microsoft.com>
Co-authored-by: JiahuiPeng <46921893+804873052@users.noreply.github.com>
Co-authored-by: edwin-msft <71858592+edwin-msft@users.noreply.github.com>
Co-authored-by: Edwin Diaz <eddiazme@microsoft.com>
Co-authored-by: dochollidayxx <dochollidayxx@gmail.com>
Co-authored-by: Adam Holliday <adamho@microsoft.com>
Co-authored-by: yifan-zhou922 <78060542+yifan-zhou922@users.noreply.github.com>
Co-authored-by: Parv Saxena <psaxena6@jhu.edu>
Co-authored-by: Parv Saxena <pasaxena@microsoft.com>
Co-authored-by: hvermis <hvermis@microsoft.com>
Co-authored-by: xuepingd <75347475+xuepingd@users.noreply.github.com>
Co-authored-by: laxmankumar12 <vlk_laxman@yahoo.com>
Co-authored-by: REDMOND\lakshv <lakshv@microsoft.com>
Co-authored-by: He Huang <47040595+hjhhh3000vitae@users.noreply.github.com>
Co-authored-by: Zed Lei <59104634+RAY-316@users.noreply.github.com>
Co-authored-by: kangsun-ctrl <69279251+kangsun-ctrl@users.noreply.github.com>
Co-authored-by: brpanask <64860651+brpanask@users.noreply.github.com>
Co-authored-by: rebecca337 <80353400+rebecca337@users.noreply.github.com>
Co-authored-by: Rebecca Dupuis <rdupuis@microsoft.com>
Co-authored-by: xunsun-commits <84804232+xunsun-commits@users.noreply.github.com>
Co-authored-by: Wan Yang <wanyang@microsoft.com>
Co-authored-by: soma-ms <84877933+soma-ms@users.noreply.github.com>

* remove blank line

* address comments

* address the description comment

* update the swagger

* remove ManagedInstances_ListOutboundNetworkDependenciesByManagedInstance

* Update from microsoft.sql 2021-05-01-preview to base branch (Azure#16184)

* Update comment.yml for publish pr (Azure#16166)

* Update comment.yml

* Update comment.yml

* Bump dependencies (Azure#16170)

* bump avocado

* bump mocha

* remove submodule (Azure#16171)

* add azure-resource-manager-schema to servicelinker (Azure#16176)

Co-authored-by: Nan Jiang <naji@microsoft.com>

* Update pr assignment config (Azure#16175)

* [Synapse] - fix scheme for Artifacts and update readme to include KQL scripts for October release (Azure#16035)

* [Synapse] - fix scheme for Notebook, Spark Job definition and SQL script

* Update dataset, linked service and pipeline

* Update release tag for october release

* Correct type of result limit

* Add arguments for SynapseSparkJobActivityTypeProperties

Co-authored-by: Dongwei Wang <dongwwa@microsoft.com>

* fix (Azure#16164)

Merging the change to have accurate Swagger

* update swagger files

* update readme.md

* add missing json files

* update custom-words.txt to address the spelling check

* remove 201 define in ServerUpdate.json

* remove blank line

* address comments

* address the description comment

* update the swagger

* remove ManagedInstances_ListOutboundNetworkDependenciesByManagedInstance

Co-authored-by: Tianen <347142915@qq.com>
Co-authored-by: Zhenglai Zhang <darinzh@microsoft.com>
Co-authored-by: Lei Ni <7233663+leni-msft@users.noreply.github.com>
Co-authored-by: najian <jiangnan8924@gmail.com>
Co-authored-by: Nan Jiang <naji@microsoft.com>
Co-authored-by: Ray Chen <raychen@microsoft.com>
Co-authored-by: Dongwei Wang <bean0idear@163.com>
Co-authored-by: Dongwei Wang <dongwwa@microsoft.com>
Co-authored-by: msyyc <70930885+msyyc@users.noreply.github.com>

Co-authored-by: Tianen <347142915@qq.com>
Co-authored-by: Zhenglai Zhang <darinzh@microsoft.com>
Co-authored-by: Lei Ni <7233663+leni-msft@users.noreply.github.com>
Co-authored-by: najian <jiangnan8924@gmail.com>
Co-authored-by: Nan Jiang <naji@microsoft.com>
Co-authored-by: Ray Chen <raychen@microsoft.com>
Co-authored-by: Dongwei Wang <bean0idear@163.com>
Co-authored-by: Dongwei Wang <dongwwa@microsoft.com>
Co-authored-by: msyyc <70930885+msyyc@users.noreply.github.com>
Co-authored-by: AriZavala2 <77034370+AriZavala2@users.noreply.github.com>
Co-authored-by: PingZhu2232 <36140352+PingZhu2232@users.noreply.github.com>
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Co-authored-by: Ping Zhu <pizh@Pings-MacBook-Pro.local>
Co-authored-by: Mohit Chakraborty <8271806+Mohit-Chakraborty@users.noreply.github.com>
Co-authored-by: Roslyn Lu <roslyn.lu@gmail.com>
Co-authored-by: Roslyn Lu <roslu@microsoft.com>
Co-authored-by: JiahuiPeng <46921893+804873052@users.noreply.github.com>
Co-authored-by: edwin-msft <71858592+edwin-msft@users.noreply.github.com>
Co-authored-by: Edwin Diaz <eddiazme@microsoft.com>
Co-authored-by: dochollidayxx <dochollidayxx@gmail.com>
Co-authored-by: Adam Holliday <adamho@microsoft.com>
Co-authored-by: yifan-zhou922 <78060542+yifan-zhou922@users.noreply.github.com>
Co-authored-by: Parv Saxena <psaxena6@jhu.edu>
Co-authored-by: Parv Saxena <pasaxena@microsoft.com>
Co-authored-by: hvermis <hvermis@microsoft.com>
Co-authored-by: xuepingd <75347475+xuepingd@users.noreply.github.com>
Co-authored-by: laxmankumar12 <vlk_laxman@yahoo.com>
Co-authored-by: REDMOND\lakshv <lakshv@microsoft.com>
Co-authored-by: He Huang <47040595+hjhhh3000vitae@users.noreply.github.com>
Co-authored-by: Zed Lei <59104634+RAY-316@users.noreply.github.com>
Co-authored-by: kangsun-ctrl <69279251+kangsun-ctrl@users.noreply.github.com>
Co-authored-by: brpanask <64860651+brpanask@users.noreply.github.com>
Co-authored-by: rebecca337 <80353400+rebecca337@users.noreply.github.com>
Co-authored-by: Rebecca Dupuis <rdupuis@microsoft.com>
Co-authored-by: xunsun-commits <84804232+xunsun-commits@users.noreply.github.com>
Co-authored-by: Wan Yang <wanyang@microsoft.com>
Co-authored-by: soma-ms <84877933+soma-ms@users.noreply.github.com>
@github-actions github-actions bot locked and limited conversation to collaborators Apr 12, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@scbedd scbedd

Labels
Client This issue points to a problem in the data-plane of the library. Cosmos Docs
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@southpolesteve @annatisch @xiangyan99 @SuperChenSSS @scbedd