Setup new documentation framework #222
Conversation
CasperWA
force-pushed
the
cwa/close-195-mkdocs-framework
branch
from
bf93187 to
e1a2fa1
Compare
|
An example of using versioned documentation can be seen by doing the following: $ cd /path/to/EMMO-python
$ git fetch origin
$ git checkout cwa/close-195-mkdocs-framework
$ pip install -e .[docs]
$ mike serve -b test-mike
Starting server at http://localhost:8000/
Press Ctrl+C to quit.Now go to http://localhost:8000 and see how the versioned documentation will look. If this is desirable, we can implement this type of documentation for the GitHub pages. However, I am unsure whether we shouldn't actually use |
I installed mike with Can you include documentation on what is needed to make it locally? |
Yes, you need to follow my instructions and install the package with the |
Fair enough 😅 Sorry for the apparent badgering then. I'll check out why it doesn't work, it should 😕 oh well 😄 |
|
I think this looks very very nice! As for the docs and demo, I am now convinced that we should only have those in the documentation :) We should definitely have documentation on ontodoc, whic is supposed to be for documenting ontologies and not python packages as you already wrote. Is there a way to make binders with this setup for e.g. a jupyter notebook example? |
Yay :)
Okay - I'll try to make them a bit nicer then.
Hmm. I'll see what I can do. Mybinder is quite slow to start up if it hasn't been run in a while, and therefore cached, but it's a good thing to have, at least. |
|
to clarify, I think we are more or less at the point that we can make the first release and then make other additions as improvements |
|
This is ready for review. It has been greenlit by @francescalb (most likely following up with an "Approved" review), but it would be good to get @jesper-friis's input before merging this in. Note, on merge this will NOT start publishing new documentation. The existing documentation (see https://emmo-repo.github.io/EMMO-python) will continue as is, one needs to (for now) manually publish this documentation if one wants to. Automating and documenting this is partly part of issue #199. However, I will create a dedicated issue for this. |
|
Argh, it seems the |
Concerning this, maybe the last two commits here should be reverted and a dedicated PR could be made, instead of trying to both change the package build as well as setup a documentation framework here? |
|
How about adding the demo and examples here now separately (copy instead of soft link), so that they are in the documentation from the start, and fix the package(eg remove them) in a separate pr? Maybe this is what you suggested? |
Yeah, this is what I suggested. However, I would keep the soft links for now, as I see no reason to pollute the history with even more MB :) |
OK :) |
Remove README under tests/.
Use the Material for MkDocs theme. Adopt `invoke` tasks to auto-generate the API references and documentation index page. Add symbolic links to the `docs/` folder to create proper links.
Collapse single pages (except for the API reference).
CasperWA
force-pushed
the
cwa/close-195-mkdocs-framework
branch
from
2b8077f to
3f3134b
Compare
Closes #193.
Closes #195.
This PR sets up a MkDocs framework.
All markdown files have been updated to follow a better
git diffstrategy with "one-sentence-per-one-line". While it's not a perfect strategy, with obvious shortcomings for "thin" terminals, it still succeeds in bringing much bettergit diffs than otherwise, where reviewing may become so difficult mistakes are made due to obscurity.A
docsextra is added, meaning one can now install all the Python dependencies needed to build the documentation as well as run a simple server locally by runningpip install -e .[docs](in the future this will bepip install EMMOntoPy[docs].Invoke tasks have been created and added to a root Python file
tasks.pyto auto-generate the Python API reference documentation, as well as update the rootindex.mdfile in the documentation from the rootREADME.md- changing relative links to match, etc.These tasks can be used for continuous deployment (CD) of the documentation.
Another task has been added to auto-update the version, where needed, in the code.
This means one can use this in CD of the package when releasing a new version.
I've also added the logo from the Settings page as the "favicon" and general logo of the documentation.
As a note, in order to close #193, we need to decide what should happen with the root folders
demoandexamples.According to the referenced issue, it is suggest to move them under
docs. In the current PR I have made symbolic links to them for now, but this might as well be settled in this PR together with the setup of the documentation framework.To test this out, you can checkout this branch (
cwa/close-195-mkdocs-framework) and run:Then go to the address it prints to your terminal and poke around.
WIth the latest inclusions this now also closes #197.
For more information see this comment below.