Towards creating a documenation page #110
Conversation
|
The make file looks like one from an ancient version of Sphinx. You could change to one generated from a current version. Having a |
|
@dalito Thanks for feedback. Did that update |
| @@ -1,3 +1,6 @@ | |||
| __pycache__ | |||
|
|
|||
| *.pyc | |||
| examples/*/*/ | |||
There was a problem hiding this comment.
I don't unsterstand this line
There was a problem hiding this comment.
Conveniently, ignore sub sub folders of examples.
Allows to unzip into folders, and git not caring
Not important for docs
There was a problem hiding this comment.
I see, but what if we want to track a subfolder in there later? I think this is a wrong solution. The gitignore file must not be polluted by such ad-hoc lines that are not evident to understand why it's here. I suggest removing this line: as long as the files are not tracked by git, git will leave them alone, so there is no need to have this.
(also, if you absolutely want to keep it, I won't lose sleep over it)
| help: | ||
| @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
|
||
| .PHONY: help Makefile |
There was a problem hiding this comment.
is this makefile correct? For reference, a complete one: https://github.com/elabftw/elabdoc/blob/master/doc/Makefile
seems the .PHONY: line is missing html target at least
There was a problem hiding this comment.
This makefile was autobuild by sphinx and not modified by me. One should only modify the conf.py file, as I did.
Seems different sphinx versions autocreate different makefile.
There was a problem hiding this comment.
We can change that on the final version. This is just preview to have discussion at next meeting.
| Then build the documentation locally: | ||
|
|
||
| ``` | ||
| make -C docs html |
There was a problem hiding this comment.
can we make it so just make html works?
There was a problem hiding this comment.
Sure we can modify it.
Currently
- in root folder add the -c option or
- in docs folder, just make
There was a problem hiding this comment.
We can change that on the final version. This is just preview to have discussion at next meeting.
| @@ -0,0 +1,35 @@ | |||
| @ECHO OFF | |||
There was a problem hiding this comment.
can we remove any windows related stuff? don't care about it. don't want to have to maintain a windows script. users nowadays will use WSL anyway, let's not pollute our codebase with .bat files.
| @@ -0,0 +1,2 @@ | |||
| sphinx | |||
| sphinx_rtd_theme | |||
There was a problem hiding this comment.
please pin to exact version
There was a problem hiding this comment.
We can change that on the final version. This is just preview to have discussion at next meeting.
We talked in the Nov. 2024 meeting about creating screenshots after importing the .eln to showcase that importing / interoperability works. (An example of all imports passing the github actions is shown for PASTA)
Here a suggestion of how that could be presented:
To build from the repository directory (the one with .git)
The build and publication process can be created as github action, but that would need to be discussed.
What do you think?