Skip to content

Readme Content Verification - need to format readmes to match template doc #4554

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
Closed
33 tasks
scbedd opened this issue Mar 12, 2019 · 6 comments
Closed
33 tasks

Readme Content Verification - need to format readmes to match template doc #4554

scbedd opened this issue Mar 12, 2019 · 6 comments
Labels
Client This issue points to a problem in the data-plane of the library. Docs

Comments

@scbedd
Copy link
Member

scbedd commented Mar 12, 2019 •
edited
Loading

The following data-plane items need to be addressed. Validation has failed on the following readme list items.

tl;dr: Readmes should have at least have sections that correspond to the main sections as defined in the template readme.

This is what the tool checks, but the ideal scenario is the readme is reworked to be somewhat like the readme example.

For a rundown on what you need to do to resolve these breaking issues ASAP, check out aka.ms/azure-sdk-analyze-failed

ITEMS

31 readmes have at least one missing required section.

  • \README.rst is missing headers with patterns:
  • Azure .+ client library for Python
  • ^Getting started$
  • ^Key concepts$
  • ^Examples$
  • ^Troubleshooting$
  • ^Next steps$
  • ^Contributing$

(the items below have identical failures as the root readme as well, explicit list omitted for brevity)

  • sdk\attestation\azure-attestation\README.md
  • sdk\synapse\azure-synapse\README.md
  • \azure-applicationinsights\README.rst
  • \azure-batch\README.rst
  • \azure-cognitiveservices-knowledge-nspkg\README.rst
  • \azure-cognitiveservices-knowledge-qnamaker\README.rst
  • \azure-cognitiveservices-language-luis\README.rst
  • \azure-cognitiveservices-language-nspkg\README.rst
  • \azure-cognitiveservices-language-spellcheck\README.rst
  • \azure-cognitiveservices-language-textanalytics\README.rst
  • \azure-cognitiveservices-search-autosuggest\README.rst
  • \azure-cognitiveservices-search-customimagesearch\README.rst
  • \azure-cognitiveservices-search-customsearch\README.rst
  • \azure-cognitiveservices-search-entitysearch\README.rst
  • \azure-cognitiveservices-search-imagesearch\README.rst
  • \azure-cognitiveservices-search-newssearch\README.rst
  • \azure-cognitiveservices-search-nspkg\README.rst
  • \azure-cognitiveservices-search-videosearch\README.rst
  • \azure-cognitiveservices-search-visualsearch\README.rst
  • \azure-cognitiveservices-search-websearch\README.rst
  • \azure-cognitiveservices-vision-computervision\README.rst
  • \azure-cognitiveservices-vision-contentmoderator\README.rst
  • \azure-cognitiveservices-vision-customvision\README.rst
  • \azure-cognitiveservices-vision-face\README.rst
  • \azure-cognitiveservices-vision-nspkg\README.rst
  • \azure-eventgrid\README.rst
  • \azure-graphrbac\README.rst
  • \azure-keyvault\README.rst
  • \azure-loganalytics\README.rst
  • \azure-servicebus\README.rst
  • \azure-servicefabric\README.rst
  • \azure-servicemanagement-legacy\README.rst
@scbedd scbedd added the EngSys This issue is impacting the engineering system. label Mar 12, 2019
@scbedd scbedd self-assigned this Mar 12, 2019
@scbedd scbedd removed the EngSys This issue is impacting the engineering system. label Mar 14, 2019
@scbedd scbedd removed their assignment Mar 14, 2019
@kurtzeborn kurtzeborn added Client This issue points to a problem in the data-plane of the library. Docs labels Mar 15, 2019
lmazuel added a commit that referenced this issue Apr 10, 2019
@lmazuel
Update .docsettings.yml
a430954 
@scbedd 
  - ['azure-cognitiveservices-anomalydetector/README.rst', '#4554']
lmazuel added a commit that referenced this issue Apr 11, 2019
@lmazuel
Anomaly detector (#4752)
b150d30 
* working on building anomaly detector folder

* updated versioning

* Update sdk_packaging.toml (#4746)

* Packaging update of azure-cognitiveservices-anomalydetector

* working on building anomaly detector folder

* updated versioning

* regenerated with latest autorest version

* Packaging update of azure-cognitiveservices-anomalydetector

* Update HISTORY.rst

* Packaging update of azure-cognitiveservices-anomalydetector

* Update .docsettings.yml

@scbedd 
  - ['azure-cognitiveservices-anomalydetector/README.rst', '#4554']

* Update shared_requirements.txt
@lmazuel lmazuel added the help wanted This issue is tracking work for which community contributions would be welcomed and appreciated label Dec 16, 2021
@Prernajha2609
Copy link

Hii I would want to contribute please guide me further

@scbedd
Copy link
Member Author

scbedd commented Oct 21, 2022

Hii I would want to contribute please guide me further

Hey @Prernajha2609, apologies for the late response, I've been quite buried under an upcoming release.

We built a markdown scanner that can evaluate documents and ensure that they follow the basic structure that we decide. In this case, we have decided that we want our readmes to at least have the major sections:

  • Azure .+ client library for Python
  • ^Getting started$
  • ^Key concepts$
  • ^Examples$
  • ^Troubleshooting$
  • ^Next steps$
  • ^Contributing$

Which pans out to markdown that follow general shape of:

# Azure storage blob client library for Python
## Getting Started
<content>
## Key Concepts
<content>
<... other headers follow>

This is a simple proxy check to ensure that the readmes cover topics that we have decided are important.

If you're still interested in contributing, I would recommend that you pick a single readme from the above list and start converting it to the shape that we laid out above.

Other readmes to reference:

If you do end up contributing a readme update, please @ me in the PR! I'm much more on top of notifications nowadays.

@shubhusion
Copy link
Contributor

shubhusion commented Dec 13, 2023 •
edited
Loading

Hi , I would also like to work on this issue. @scbedd

@scbedd
Copy link
Member Author

scbedd commented Dec 13, 2023

Instructions are above! Contributions are always welcome 👍

@shubhusion
Copy link
Contributor

shubhusion commented Dec 15, 2023 •
edited
Loading

@scbedd can you provide me a resource on how to run the markdown scanner ?

@mwynne mwynne mentioned this issue Jan 24, 2024
Merged
6 tasks
@kristapratico kristapratico removed the help wanted This issue is tracking work for which community contributions would be welcomed and appreciated label Jan 25, 2024
@kristapratico
Copy link
Member

Closing, since this should be addressed in the python generator for the listed libraries

@github-actions github-actions bot locked and limited conversation to collaborators May 7, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Client This issue points to a problem in the data-plane of the library. Docs
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@lmazuel @kurtzeborn @kristapratico @scbedd @Prernajha2609 @shubhusion