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

Migrate documentation from Sphinx to Mkdocs #78

Closed
5uperpalo opened this issue Jan 17, 2022 · 2 comments
Closed

Migrate documentation from Sphinx to Mkdocs #78

5uperpalo opened this issue Jan 17, 2022 · 2 comments
Assignees

Comments

@5uperpalo
Copy link
Collaborator

5uperpalo commented Jan 17, 2022

main inspiration : https://towardsdatascience.com/five-tips-for-automatic-python-documentation-7513825b760e

  • see branch
  • current issue - I am adjusting the automate script
@5uperpalo 5uperpalo self-assigned this Jan 17, 2022
@5uperpalo
Copy link
Collaborator Author

  • automate.py script goes through whole library and gathers funbctions and classes
    puts them into mkgendocs.yml
  • gendocs util tranforms mkgendocs.yml into .md files in docs_mk
  • mkdocs build tranforms md files in docs_mk into documentation in /site
  • [optional] mkdocs serve will create http server to check the documentation
  • [optional] running of automate script can be part of prehook, but this add additional overhead so I think it's enough to keep the procedure only in readme.md or somewhere else

notes:

  • mkdocs does not like classes without init(), so I added init(self):pass where it was missing
  • automate script uses improtlib which does not like relative imports so I changed relative import "from .wdtypes import *" at couple of places to absolute path

procedure to generate documentation (all in root dir):

pip install -r mkdocs_requirements.txt
python automate.py
gendocs --config mkgendocs.yml
mkdocs build
# if you want to run webserver
# mkdocs serve

@5uperpalo
Copy link
Collaborator Author

  • jupyternotebook are now displayed in documentation - each notebook has to start with level 1 heading, I adjusted couple of notebooks that started with level 2
  • mkgendocs copies everything from templates dir to sources_dir (sources_dir is recreated each time), if we want to have examples/notebooks/*.ipynb in the documentation we have to copy them to templates ourselves - fixed it at the end of automate.py
  • markdown "image links" in readme.md were not displayed correctly, I changed them to HTML - fixed
  • I changed mknotebooks plugin to mkdocs-jupyter as new one includes scrollbar if printout is wider than width of webpage(eg pandas with many columns)
  • I copied webpage(documentation) related files (pictures, favicon, etc) to docs_mk/templates, again as contents of this directory is copied to docs_mk/sources when gendocs is run

summary
new documentation looks awesome! @jrzaurin let me know when you have time and I can give you 15min tour how it works, afterwards I create pullrequest to merge the changes

@5uperpalo 5uperpalo linked a pull request Apr 25, 2022 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants