Ordering Topics in mkdocs.yml file alphabetically

[dev-arminder]

Hi @mehdihadeli is anyone working on this issue ? If not could you please assign it to me ?

[mehdihadeli]

Hi, No, It is open, You can pick it up :) Thanks

[dev-arminder]

For Requirement clarification , we need to sort out (in alphabetical order i.e a, b, c... ) name of topics after nav in mkdocs.yml i.e. after line no 55, manually or programmatically.

[mehdihadeli]

Just, we need to sort all child elements bellow nav element (line 58 here).

[ibharathboga]

Hello @mehdihadeli ,

I hope your day is going well.

I've noticed this issue is still open. May I contribute to it? It seems straightforward to me, and I'm genuinely excited since this would be my first contribution. Your kind guidance would be invaluable.

This is what i did until now,

• forked the repo, created a branch ["ordering-topics-mkdocs"] and got into it.
• did some observation which lead me to the below doubts,
  • doubt 1 : on "Azure No-SQL" at line 320, do i add "-" or leave it as is ?
  • doubt 2 : on "Others: others.md", should i place it at the last position or in its sorted place?

• regardless of the doubts, i have written a python script to sort it :

import yaml

def sort_dict_list(dicts):
    return sorted(dicts, key=lambda kv: list(kv.keys())[0].lower())

def process_navtree(input_filename, output_filename, base_node):
    data = yaml.safe_load(open(input_filename))
    navtree = sort_dict_list(data[base_node])

    for index, enode in enumerate(navtree):
        enodekey, enodevalues = list(enode.keys())[0], list(enode.values())[0]

        if not isinstance(enodevalues, (str, list)):
            print(f"{enodekey} : {enodevalues} / neither string not list / values ERROR")
            assert False

        if isinstance(enodevalues, str):
            continue

        enodevalues = sort_dict_list(enodevalues)
        navtree[index] = {enodekey: enodevalues}

    with open(output_filename, "w") as output_file:
        yaml.dump(navtree, output_file)

#input_filename being just the content under nav
input_filename = "initial.yaml"
output_filename = "final.yaml"
base_node = "nav"

process_navtree(input_filename, output_filename, base_node)
#navtree

I am confident that executing this script gives desired result. Please let me know if there are any changes that i have to make

[mehdihadeli]

Hi @ibharathboga, Yes, It will be great if you contribute on this part. About your doubts:

1. maybe it's better we change it to Azure NoSQL for better integration with other sections because we have a dedicated section NoSQL also.
2. It should be sorted I'm not a python developer but if you think it is ok, please sort the content of mkdocs.yml file (nav section) and send a pull request for that. So thanks :)

[ibharathboga]

I have applied the necessary changes and submitted a pull request. Kindly review.

[mehdihadeli]

Thanks for helping, Merged :) Also I'm thinking about writing a github action workflow for sending a pull request automatically if we have some ordering changes automatically. (with using some scripts like your script)

[ibharathboga]

You're welcome! I'd be happy to work on this automation script with you.

I do not have prior experience with Github Actions. If that is a problem, I am willing to spend some time learning about it. Please guide me on what I need to do.

[mehdihadeli]

Thanks. Maybe I use this create-pull-request plugin for sending a pull request inner a GitHub workflow with name of sorter.yaml. inner this workflow after setup os (linux) and our dev environment like .net, nodejs,... we can run our script for example a sort script and after that we can send its result in a pull request with using create-pull-request plugin.

[ibharathboga]

I've spent some time gaining a basic understanding of the GitHub workflow. I believe there might be a way to sort the nav content automatically after each repo update without having to create a pull request. I may be mistaken, but my observation is based on the below YAML file.

name: Update Mkdocs

on:
  push:
    paths:
      - 'mkdocs.yml'

jobs:
  update-yml:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2

      # Necessary steps to update the mkdocs.yml file here

Of course, if you think creating a pull request is a better approach, I have no issues.

[mehdihadeli]

Yes, It works. but from security perspective I think we have to give a full write permissions to workflow and maybe it is not safe, currently I prefer sending a pull request with workflow after change in the yaml file. the changes for sort is not very much, so we don't have many pull requests.

[ibharathboga]

# ! pip install PyYAML
import yaml

def sort_dicts(content):
    for edict in content:
        for ekey, evalue in edict.items():
            if isinstance(evalue, list):
                edict[ekey] = sort_dicts(evalue)
    return sorted(content, key=lambda x: list(x.keys())[0].lower())

def sort_section(ifilename = "mkdocs.yml", basenode = "nav", ofilename = "mkdocs.yml"):
    data = yaml.safe_load(open(ifilename))
    data[basenode] = sort_dicts(data[basenode])
    yaml.dump(data,open(ofilename,"w"))    

sort_section()

Hi @mehdihadeli , I did not consider the security perspective, my bad. I worked on writing the above script (It took longer than expected). I ran it on a few manually modified samples of mkdocs.yml file and it works as expected.

[mehdihadeli]

Hi, Thanks for spending your time on this, Could you create a github action workflow also for this script?