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.

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

Update the documentation #434

Closed
16 tasks done
FlorianK13 opened this issue Mar 16, 2023 · 6 comments · Fixed by #460
Closed
16 tasks done

Update the documentation #434

FlorianK13 opened this issue Mar 16, 2023 · 6 comments · Fixed by #460
Assignees
Labels
📖 documentation Improvements or additions to documentation

Comments

@FlorianK13
Copy link
Member

FlorianK13 commented Mar 16, 2023

Deadline: 15.10.2023

Our documentation page is not really up to date. I heard from some people that they have problems using the open-mastr based on the documentation page.

  • Create mkdocs infrastructure files @FlorianK13
  • Create root structure @FlorianK13
  • Update docstrings @FlorianK13
  • The dataset - Soap API @chrwm
  • The dataset - CSV @chrwm
  • Add mike versioning
    - [ ] Check if mike versioning works on readthedocs @chrwm
  • Put all advanced pages in a advanced.md file @FlorianK13
  • Document bulk functionalities in Advanced or References (High level mermaid diagram mastr website to sqlite to csv) @FlorianK13
  • index.md: Merge table 'Contributions of open-mastr' with existing bullet points @chrwm
  • Document the MaStRAPI bindings explicitly, maybe in getting started @chrwm
  • Screenshot from DBBrowser at getting started @FlorianK13
  • datasets.md put description of tables in an tabs element @FlorianK13
  • datasets.md put original data model screenshot and translated on in tabs element @FlorianK13
  • advanced/config.md see if the project directory descrpition is up to date and add descriptions for missing files / folders @chrwm
  • Delete all unused .rst files when the work is finished @FlorianK13 @chrwm

Ideas of solution

We have outdated chapters that can be deleted - they still can be accessed if the documentation of earlier versions is still hosted in readthedocs.

Workflow checklist

@FlorianK13 FlorianK13 added the 📖 documentation Improvements or additions to documentation label Mar 16, 2023
@chrwm
Copy link
Member

chrwm commented Mar 16, 2023

In my opinion we should update the sphinx theme, RTD is not very pretty.
https://sphinx-themes.org/

We should consider to move from sphinx to mkdocs due to the simplicity of editing markdown compared to rst.
https://squidfunk.github.io/mkdocs-material/

@FlorianK13
Copy link
Member Author

When migrating the documentation from .rst to .mk this would also give the opportunity to sort out old stuff.

@FlorianK13
Copy link
Member Author

FlorianK13 commented Jul 13, 2023

We could have the following structure. I marked chapters with bounding boxes and descriped a bit of the content. Some of the names could be chosen better, so we have to discuss this further. What do you think @chrwm ?

Main Content:

  • Getting started
    • Downloading the MaStR data
    • Accessing the database
    • Exporting data to csv
  • The dataset: Structure of newly created folders
    • Database: How to change to postgres etc, which tables you get, what data they contain
    • CSV: Which files you get, what they contain, how they are created
    • The two data sources
      • xml Download
      • Soap API: Getting API credentials
  • Development: Also adding new tools we use: pre-commit hooks, the different github actions, the guide to publish the python package, etc.
  • API-Reference

Few more thoughts:

  • Instead of documenting the data and the API functions, we should refer to the documentation at marktstammdatenregister.de By doing so, we don't need to update our documentation every time the data changes.

FlorianK13 added a commit that referenced this issue Jul 24, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
@FlorianK13
Copy link
Member Author

@chrwm and me think about converting the documentation to mkdocs and hence use .md files for the documentation.

@Ludee I remember that you intentionally switched to .rst files, especially for the Readme.rst. Can you shortly name the reasons for doing so?

FlorianK13 added a commit that referenced this issue Aug 7, 2023
FlorianK13 added a commit that referenced this issue Aug 7, 2023
@chrwm chrwm mentioned this issue Aug 7, 2023
5 tasks
chrwm added a commit that referenced this issue Aug 7, 2023
FlorianK13 added a commit that referenced this issue Aug 9, 2023
FlorianK13 added a commit that referenced this issue Aug 9, 2023
FlorianK13 added a commit that referenced this issue Aug 9, 2023
FlorianK13 added a commit that referenced this issue Aug 9, 2023
FlorianK13 added a commit that referenced this issue Aug 9, 2023
FlorianK13 added a commit that referenced this issue Aug 9, 2023
FlorianK13 added a commit that referenced this issue Aug 23, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
chrwm added a commit that referenced this issue Aug 29, 2023
* deploys documentation on github pages
chrwm added a commit that referenced this issue Aug 29, 2023
chrwm added a commit that referenced this issue Aug 29, 2023
chrwm added a commit that referenced this issue Aug 29, 2023
chrwm added a commit that referenced this issue Aug 29, 2023
FlorianK13 added a commit that referenced this issue Aug 30, 2023
FlorianK13 added a commit that referenced this issue Aug 30, 2023
FlorianK13 added a commit that referenced this issue Aug 30, 2023
chrwm added a commit that referenced this issue Sep 25, 2023
chrwm added a commit that referenced this issue Sep 25, 2023
chrwm added a commit that referenced this issue Sep 26, 2023
@FlorianK13 FlorianK13 mentioned this issue Sep 27, 2023
5 tasks
FlorianK13 added a commit that referenced this issue Sep 27, 2023
FlorianK13 added a commit that referenced this issue Sep 27, 2023
FlorianK13 added a commit that referenced this issue Sep 27, 2023
Together with chatGPT
@FlorianK13 FlorianK13 linked a pull request Nov 2, 2023 that will close this issue
5 tasks
FlorianK13 added a commit that referenced this issue Nov 20, 2023
FlorianK13 added a commit that referenced this issue Nov 20, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📖 documentation Improvements or additions to documentation
Projects
None yet
4 participants