Multiple versions of docs
adibrastegarnia opened this issue · comments
Hi
I want to use this plugin for a project but it is not clear for me how docs should be organized? Should we have multiple folders for each version? The example shows just one version. That would be nice to extend to show a multi version example
Thanks
in the readme, there is a link which documents how to use the plugin, https://zayd62.github.io/mkdocs-versioning/
Let me know if the documentation is unclear
Please help, how to show multiples version as the picture did, I noticed your yaml file only contains one
This is how my project loos like, I want to add version 1.0.0 as you did, please tell me how.
you write your docs then put a version number 1.0.0 for example, then build and commit. then write docs for the next version number 1.1.0, build then commit. you will then find that the version page has 1.0.0 and 1.1.0.
the yaml only contains the version number you want to build. more details as to how it works is available here: https://zayd62.github.io/mkdocs-versioning/0.1.0/#how-does-it-work
you write your docs then put a version number
1.0.0for example, then build and commit. then write docs for the next version number1.1.0, build then commit. you will then find that the version page has1.0.0and1.1.0.the yaml only contains the version number you want to build. more details as to how it works is available here: https://zayd62.github.io/mkdocs-versioning/0.1.0/#how-does-it-work
I'm confused about the commit here, how and where should I commit?
using https://github.com/zayd62/mkdocs-versioning-test as an example.
- version 1.0.0 --> circle page
- version 1.1.0 --> circle and triangle page
The above is an example software release cycle
1.0.0
mkdocs.yml looks like:
site_name: <SITE NAME>
repo_url: <URL GOES HERE>
repo_name: <USERNAME/REPOSITORY_NAME>
edit_uri: ''
plugins:
- mkdocs-versioning:
version: 1.0.0
nav:
- Home : 'index.md'
- Circle: 'circle.md'
- Version: '../'
your source code directory looks like this. (ignoring the actual source code itself)
.
├── docs
│ └── circle.md
└── mkdocs.yml
run mkdocs build and the site directory (where mkdocs stores the built docs) will look something like this:
├── 1.0.0
│ ├── 404.html
│ ├── assets
│ ├── circle
│ ├── index.html
│ ├── search
│ ├── sitemap.xml
│ └── sitemap.xml.gz
├── 404.html
├── assets
│ ├── fonts
│ ├── images
│ ├── javascripts
│ └── stylesheets
├── index.html [1]
├── search
│ └── search_index.json
├── sitemap.xml
└── sitemap.xml.gz
Note: index.html [1] is the version selection page (https://zayd62.github.io/mkdocs-versioning-test/) and is automatically built
Now that the docs are built, you commit changes to the repository (you do NOT commit the built docs, source code only). If you want to deploy the built docs to Github pages, run the command mkdocs-versioning deploy (https://zayd62.github.io/mkdocs-versioning/0.1.0/CLI%20commands/#deploy)
Now, version 1.0.0 of your docs are built, deployed and stored in your github repository
1.1.0
now its time for version 1.1.0 and you need to add a triangle page
mkdocs.yml
site_name: <SITE NAME>
repo_url: <URL GOES HERE>
repo_name: <USERNAME/REPOSITORY_NAME>
edit_uri: ''
plugins:
- mkdocs-versioning:
version: 1.1.0
nav:
- Home : 'index.md'
- Circle: 'circle.md'
- Triangle: 'triangle.md'
- Version: '../'
your source code directory looks like this. (ignoring the actual source code itself)
.
├── docs
│ ├── circle.md
│ └── triangle.md
└── mkdocs.yml
run mkdocs build and the site directory (where mkdocs stores the built docs) will look something like this:
├── 1.0.0
│ ├── 404.html
│ ├── assets
│ ├── circle
│ ├── index.html
│ ├── search
│ ├── sitemap.xml
│ └── sitemap.xml.gz
├── 1.1.0
│ ├── 404.html
│ ├── assets
│ ├── circle
│ ├── index.html
│ ├── search
│ ├── sitemap.xml
│ ├── sitemap.xml.gz
│ └── triangle
├── 404.html
├── assets
│ ├── fonts
│ ├── images
│ ├── javascripts
│ └── stylesheets
├── index.html [1]
├── search
│ └── search_index.json
├── sitemap.xml
└── sitemap.xml.gz
Note: index.html [1] is the version selection page (https://zayd62.github.io/mkdocs-versioning-test/) and is automatically built. this time, it will have 1.0.0 and 1.1.0 as an option. how it determines this is by simply looking at what docs are already built. we have a folder 1.0.0 and a folder 1.1.0 so the version selection page has links to both versions.
Now that the docs are built, you commit changes to the repository (you do NOT commit the built docs, source code only). If you want to deploy the built docs to Github pages, run the command mkdocs-versioning deploy (https://zayd62.github.io/mkdocs-versioning/0.1.0/CLI%20commands/#deploy)
The important bit is the reliance of the built docs to build the version selection page. the version page only builds links to version of the docs available in the site directory with the appropriate site directory layout
I do have documentation available here https://zayd62.github.io/mkdocs-versioning/ but it seems that my documentation is a bit vague so will need improving (#23). There are also more feature that i want to add (#1, #11) and i do have some ideas on how the versioning system can be improved/changed (#4, #10).
Again this is currently in alpha and still an active project (university taking priority) so i do appreciate any feedback and ideas.
I hope this is a bit more clear on how the versioning system work. i know it sees quite complicated (and this wall of text doesn't help) but I do believe that versioning is an important part of software engineering hence why i decide to make this plugin.
To answer your question about the commit, you commit after your docs are built because that way, you are marking the end of developing a certain version. this commit should also have a git annotated tag with the version number. ideally, you write documentation as you code your project but you build and deploy the docs once once you finished the code
Thanks for your so detailed reply, as you introduced, I first deploy version 1.0.0 by mkdocs build and mkdocs-versioning deploy, and it works. And a version select with 1.0.0 is shown in the selector page. Here's my mkdocs.yaml:
site_name: 'All about shapes'
repo_url: 'https://github.com/zayd62/mkdocs-versioning-test'
repo_name: 'zayd62/mkdocs-versioning-test'
theme: 'material'
edit_uri: ''
plugins:
- search
- mkdocs-versioning:
version: 1.0.0
markdown_extensions:
- admonition
- pymdownx.arithmatex
- pymdownx.details
- codehilite:
guess_lang: false
- toc:
permalink: true
extra_javascript:
- 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'
nav:
- Home: 'index.md'
- Shapes:
- Circle: 'circle.md'
# - Triangle: 'triangle.md'
# - Quadrilateral: 'quadrilateral.md'
- Version: '../'
Then I made some changes in the mkdocs.yaml, I change the version to 1.1.0 and add some new contents in doc.
But When I try to build with mkdocs build, some errors are thrown as follow:
INFO - Cleaning site directory
INFO - Building documentation to directory: /Users/zhangying/mkdocs-versioning-test/site/1.1.0
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
- triangle.md
WARNING - A relative path to '../' is included in the 'nav' configuration, which is not found in the documentation files
Traceback (most recent call last):
File "/Library/Frameworks/Python.framework/Versions/3.7/bin/mkdocs", line 10, in <module>
sys.exit(cli())
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 764, in __call__
return self.main(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 717, in main
rv = self.invoke(ctx)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 1137, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 956, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 555, in invoke
return callback(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/__main__.py", line 163, in build_command
), dirty=not clean)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/commands/build.py", line 298, in build
config['plugins'].run_event('post_build', config)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/plugins.py", line 94, in run_event
result = method(item, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkversion/entry.py", line 45, in on_post_build
version(config, self.config)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkversion/version.py", line 47, in version
os.remove(f.path)
PermissionError: [Errno 1] Operation not permitted: '/Users/zhangying/mkdocs-versioning-test/site/search'
Though a file named 1.1.0 is generated in the site, but I found the page is 404 after I run the command mkdocs-versioning deploy. Please help, and thanks again.
I tried another time and the same error happens when I build version 1.1.0.
INFO - Cleaning site directory
INFO - Building documentation to directory: /Users/zhangying/versions/site/1.1.0
WARNING - A relative path to '../' is included in the 'nav' configuration, which is not found in the documentation files
Traceback (most recent call last):
File "/Library/Frameworks/Python.framework/Versions/3.7/bin/mkdocs", line 10, in <module>
sys.exit(cli())
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 764, in __call__
return self.main(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 717, in main
rv = self.invoke(ctx)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 1137, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 956, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/click/core.py", line 555, in invoke
return callback(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/__main__.py", line 163, in build_command
), dirty=not clean)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/commands/build.py", line 298, in build
config['plugins'].run_event('post_build', config)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/plugins.py", line 94, in run_event
result = method(item, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkversion/entry.py", line 45, in on_post_build
version(config, self.config)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkversion/version.py", line 47, in version
os.remove(f.path)
PermissionError: [Errno 1] Operation not permitted: '/Users/zhangying/versions/site/search'
And I notices there is no index.html in my case.
sorry for the late reply, been busy with university. just briefly looking at your error message, the PermissionError seems to suggest that the user running the program does not have the correct permissions to delete the file. https://docs.python.org/3/library/exceptions.html#PermissionError
one possible explanation is that it is trying to delete some system files although it shouldn't be doing that. PermissionError: [Errno 1] Operation not permitted: '/Users/zhangying/versions/site/search' seems to suggest that the code should have the right permissions to delete because that path should be owned by the user.
I suggest that you completely start over. delete all the files related to the project ,uninstall the plugin, reinstall the plugin (should be using python virtual environment https://realpython.com/python-virtual-environments-a-primer/ although i prefer conda (completely up to you though) https://docs.conda.io/en/latest/)
write version 1.0.0 of docs. build, write version 1.1.0, build using the instructions above and then use the built in http server in python python3 -m http.server . I do plan on adding new features and fixing the documentation during university holidays.
Also, i will be closing this issue as this has transitioned from the documentation being unclear to errors within the code. If your issue is not fixed, please open a new issue and i will be more than happy to help.
I am having the same issue as Amber1990Zhang in which the folders generate correctly (although while throwing the permission error) but the older versions of the document builds are simply overwriting in the Version Select view, even after trying to add on to the extra config section as seen through some of the documentation. This is the last major thing I'm stuck on and am playing with this on a small scale before I hope to implement it into a much larger project.
And I understand the build and commit portion but from an experimentation standpoint, shouldn't build update/generate the Version Select page navigation options? I haven't connected my project to any git repo as again it's for mere experimentation at this point, but is it waiting on a git command to flag it for the update? I could have a local git repo which is my next avenue of testing but it does seem unnecessary from a function-initiation standpoint where the build command can simply do the same thing.
I'm completely new to this so please walk me through it more!
As for your documentation, that would be the main recommendation as I've been to your test site which I found great for a demo but not great for walking me through how to replicate it (which is actually what I'm trying to do right now). Even if the test site had different branches so that I may literally compare the code changes it would be much more helpful (example as NASA OpenMCT style https://github.com/nasa/openmct-tutorial that walks through checking out different branches).
kindly get this link up or atleast share code of below test example please ?