Docs via mkdocs #589
Docs via mkdocs #589
Conversation
| dmypy.json | ||
|
|
||
| # editor | ||
| .vscode |
There was a problem hiding this comment.
And I think we can move the Rstudio bit to a place where it's less front-and-center. Not that many folks will use it.
There was a problem hiding this comment.
Should RStudio queue on the user guide? At the end of the day it is a tutorial just as the others?
koaning
left a comment
koaning
left a comment
There was a problem hiding this comment.
Left some initial comments. In short: this looks great and thanks for the effort!
| dmypy.json | ||
|
|
||
| # editor | ||
| .vscode |
There was a problem hiding this comment.
And I think we can move the Rstudio bit to a place where it's less front-and-center. Not that many folks will use it.
|
I just approved the docstrings PR. I think once you agree it's good to merge in we can sync it here and start work on getting this merged in. 👍 |
|
@FBruzzesi could you fix the optional dependencies CI job? I think runing |
| # site_description: tbd | ||
| # site_url: tbd |
There was a problem hiding this comment.
Left both to compile in the future
|
Yeah those warnings are annoying, but as long as there's a test in CI that confirms that it's still able to build then I think we can live with it. One detail, I pay for mkdocstrings via their insiders program so if I render the page I can get a big of extra sugar on the methods/classes like here.
|
|
@FBruzzesi maybe as a final step, could we add a CI file like this one? name: Confirm MKdocs can build
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
max-parallel: 4
matrix:
python-version: [3.9]
os: [ubuntu-latest]
steps:
- uses: actions/checkout@v1
- name: setup ${{ matrix.python-version }}
uses: actions/setup-python@v1
with:
python-version: ${{ matrix.python-version }}
- name: install
run: |
make install
- name: build docs
run: python -m mkdocs buildJust to confirm that the docs can build on each PR? |
| - name: Docs can Build | ||
| run: | | ||
| sudo apt-get update && sudo apt-get install pandoc | ||
| python -m pip install -e ".[docs]" | ||
| sphinx-build doc docs | ||
| mkdocs build |
There was a problem hiding this comment.
as a final step, could we add a CI file like this one?
@koaning how's that different from the one we have here?
There was a problem hiding this comment.
Ah! I somehow missed that. LGTM then :)
That's a nice touch! Indeed you are also the only one to be able to deploy them in any case 😂 BTW the meth for method is just hilarious |
| validation: | ||
| absolute_links: ignore | ||
| unrecognized_links: ignore |
There was a problem hiding this comment.
Found these parameters to have waaaaaaaay less info/warning when building the docs
2 participants
Description
This PR substitutes the sphinx docs in favor of mkdocs style via mkdocs-material and mkdocsrings-python (depends on #586).
In particular it migrates all the notebooks directly to markdown files (almost one-to-one mapping).
Render locally
To render the documentation locally, you can run the following command from the root of the repository:
make docsThen the documentation page will be available at localhost.
Remark
The majority of code displayed in the markdowns and code generate plots in the documentation is generated using the scripts in the
docs/_scriptsfolder, and then accessed via the pymdown snippets extension.To generate the plots from scratch it is enough to run the following command from the root of the repository:
which will run all the scripts and save results in the
docs/_staticfolder.Notice that not every image is code generated!