search

jupyter / accessibility

A repository for ongoing work around making Jupyter's software accessible and inclusive
https://jupyter-accessibility.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
66 stars 33 forks source link

Enhanced Contribution Guide & Read The Docs #82

Closed pws1453 closed 2 years ago

pws1453 commented 2 years ago

We added some resources into the CONTRIBUTING.md and the Read The Docs. Let us know of any feedback or suggestions you may have!

gabalafou commented 2 years ago

If you're not sure what to do about duplication and you're not finding any good solutions, I think one solution would be to simply replace the redundant content in the markdown files with links to the same content on the RTD site. For example, perhaps instead of having a README.md full of content, it would just say something like:

All documentation about this repo is on Read The Docs.

bay1877 commented 2 years ago

Hi, big apologies for the delay. I was swamped for a while with my school work. Looking to get to the feedback today and make the suggested improvements.

bay1877 commented 2 years ago

Okay, so I drafted a potential solution to avoid duplicated information. Certainly open to feedback on the approach, especially on preferred naming and directory/file placement.

My initial design/solution is the following...

As pointed out, some of the information between the README.md and the index.md (the new home page of the read the docs) was repeated/duplicated. Originally, the home page of the read the docs was just the README.md file, and I wasn't a huge fan of this for some of the same reasons (homepage covered more detail than needed/repeated sections like the "get involved section".

I broke down the README.md into three "chunk" markdown files for each of the sections, and I put them into ./docs/readme_chunks. I made a bash script ./docs/readme_chunks/generate_frontpage_documents.sh that took these chunks and generated the index.md and the README.md. Instead of having to modify information in two places, simply modify the right "chunk" and then run the script to generate both documents.

Pros vs Cons to this approach: pros -> prevents duplicate information/changes cons -> adding a new "chunk" to either now requires adding a new chunk md file and updating the generation script to concatenate it into the right place.

In other words, this approach helps when modifying existing information chunks, but adding a new chunk/section of a different topic would be slightly more difficult. The script isn't very hard to figure out, but it is definitely not as easy as just modifying a markdown file.

relevant commits: https://github.com/jupyter/accessibility/pull/82/commits/2d793278dabc987fb8d4aab29c1aa6d9e07ffd10 https://github.com/jupyter/accessibility/pull/82/commits/a2b9ba937e168b841f606b7cb8003abe5a9a2524

pws1453 commented 2 years ago

Made a python version of this. The code has internal references to existing chunks, but these references can be added to with ease. Additionally, external code can easily grab a list of chunk paths. To add a chunk to the script, the chunk path would be added as a variable, which would need to be added to the return value of get_chunk_paths. This file would also need to be opened and its lines read into a variable, as done in __parse_files. This code works well for the files that need to be written in this PR, and could be further modularised with ease (one of the nice things about OO) in case this chunked approach was to be re-used in other contexts.

pws1453 commented 2 years ago

First - Sorry for the delays. Finals hit and I've just begun a new internship.

I think the best solution may be that we establish a 'single source of truth', as previously suggested by @gabalafou , whether that be the RTD or the Github readme, and link one to another. This would reduce developer confusion, and allows the community to avoid keeping up the chunking subsystem.

We could also have CI make a copy of the 'single source of truth' upon a new commit to master to wherever we need the source to be copied to. However, this is another thing to upkeep. I will definitely recommit without the .vscode files - missed those. Sorry.

gabalafou commented 2 years ago

@pws1453 congrats on the internship and thanks for following up!

I prefer the first solution you mention (linking) rather than using CI (because of upkeep, as you mention).

Will you be able to update this PR?

trallard commented 2 years ago

Since this has been open for a while with no movement - I will close this PR as #106 tackles many of the review issues.

I will however add @pws1453 as a co-author in #106 since I used some of the structure and other work here to move the other PR 🙏🏽