To improve document
xinetzone opened this issue · 23 comments
To add a subdomain, see custom-domain-support.
Do not use invoke doc.update to prevent damage to locals/ content.
What I am missing is this: https://pythonrepo.com/repo/executablebooks-sphinx-autobuild-python-documentation
I don't really want to implement anything myself. It seems however, that it's not easily possible to specify a custom build command for this one, so it won't play along with multiple steps to create the site.
There's another idea for the Sphinx theme.
sphinxawesome: Supports custom navigation bar.
pydata-sphinx-theme might be better.
We have customized/tuned the RTD theme heavily, so it works well on mobile, social buttons, etc. and cannot really invest the time right now to repeat that effort, so changing the theme is not really what I am looking at.
The version switcher mechanism of Sphinx is unused right now, only the latest website version is offered. Maybe indeed it could make sense to use that to switch languages, but I don't think it's about localization. And then, of course, not all documents are to be localized.
I need to think what to do with API, so there the version could make sense, but honestly, I am happy with only the latest version of the API being accessible. Like I said, API probably should become its own site, similar to intl as it is something entirely different and right now is the only reason a normal web page author or translator needs to check out Nuitka at all.
For language switching, I think the post-processing or templating (we do override some templates already), could be used. I was going to look at what other people have there.
As real problems go we have right now, there are two locales folders, which fooled me shortly. The top level one is apparently unused, I am going to remove it. Then, the blog plugin is used for locales, and generates stuff that makes no sense. I will remove it shortly.
There are still cleanups to do. Also, I think the scope of the pages needs adaptations. I saw your translated developer manual, I don't think that should be done. Developers of Nuitka would have to be English speaking, for me this translation is more for developers that use Nuitka and will have an easier time if it's not in English, or be able to do it at all.
When @Fire-Cube starts doing German, I think I will have a better chance to work on the structure of the thing. I believe it should be closer to the original navigation. For untranslated content, I think a page that says that in some standard fashion would be nice, such that we e.g. do not offer language switching on roadmap, yet there is a page with a Chinese statement at the top, that says that the roadmap information is in English, and link to the that.
two locales/, I already cleaned it up.
It might be more convenient to create a new page switcher.rst. see brach switcger.
ok, you have disabled parts the workflow though, and post processing also, so currently main has breaking changes, does it? Maybe we don't use main for development and instead only translation as a target, for me it's strange that I would have two branches of very different status. Are you ok, with moving back using that branch, also also have gh-pages fed from there?
If you don't mind, what I would do now, is to branch main as translation, and force push the currently accepted, i.e. merged state of the website in its place. Then we click merge, when translation looks good on Github pages and start new changes there, that way I can have a stable website. As you can imagine, I don't want to be stressed out by the website breaking down.
Done, I am going to work on the post-processing, such that there can be hope for it, to look correct on Github pages, since it will make absolute relative paths be relative to the page.
In the future, maintain both branches simultaneously. If translation is ok, merge back to main; If there is a problem with translation, then pull from main to translation.
Exactly, translation should be merged frequently. I basically will setup something that makes a competent diff of the result, such that I can decide if it's only improvements. But generally, I want you to look at gh-pages and have it good.
Right now I deployed the state from yesterday like this: https://nuitka.net/zh_CN/
I will be working directly on main (after working on a branch privately) to get the post processing to make gh-pages look acceptable, right now I think all CSS, image links, etc. must be broken, whereas download page has images correctly right now.
Not sure if you understand the problem, but /_static is used by Sphinx in the generated HTML content. But we didn't tell it during generation about the target URL, so this is wrong. Also in a few places, and generally, I would like to be able to just use absolute rather than relative URLs, in the source. The post processing can just update URLs easily. It already visits all images, and links anyway. This is naturally another potentially breaking change.
The alternative is probably to tell Sphinx about the different target URL. More though needs to be put into this, but on the other hand, I see it as important that translation is attempted to be rendered nicely as soon as possible.
For developing and testing breaking changes, so far I have a staging website that I use, https://staging.nuitka.net/ where I prepare changes like e.g. currently: https://staging.nuitka.net/posts/python-compile-windows.html until I deem them ready, and I guess, I could automatically make that job that builds it compare stuff with current main.
Esp. I do not think, you have to do anything about the images by moving them in the repo right now.
A new solution: using the pydata-sphinx-theme theme theme + Read The Docs.
Case: xyzstyle.
conf.py
# ``pydata-sphinx-theme`` 配置
# Define the json_url for our version switcher.
json_url = 'https://nuitka.net/_static/switcher.json'
version = 'zh_CN'
switcher_version = version
if "dev" in version:
switcher_version = "dev"
elif "rc" in version:
switcher_version = version.split("rc")[0] + " (rc)"
html_theme_options = {
"switcher": {
"json_url": json_url,
"version_match": switcher_version,
"url_template": "https://pandas.pydata.org/{version}/",
}
}https://nuitka.net/_static/switcher.json
[
{
"name": "zh_CN",
"version": "latest",
"url": "https://nuitka.net/zh_CN/latest"
},
{
"name": "main",
"version": "main",
"url": "https://nuitka.net/main"
}
]Read The Docs:
readthedocs.yml:
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
python: "3.10"
# You can also specify other tool versions:
# nodejs: "16"
# rust: "1.55"
# golang: "1.17"
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
# Build PDF & ePub * HTML
formats:
- htmlzip
- epub
# - pdf
# Optionally declare the Python requirements required to build your docs
python:
install:
- method: pip
path: .
extra_requirements:
- doc
system_packages: truemore details in readthedocs config-file/v2.
I can't really switch the theme anymore, too much effort has been put into fine tuning its performance. I will try and finish the switcher, it's really only a matter of CSS styling, that is holding me back, which is a shame, since it's been too long indeed.
I think this is resolved. The language switcher is in place, I think files need to be moved, so they can be linked to another, they need to be same hierarchy, otherwise it ought to be good. I will look into moving files when I debug the language switcher, which currently apparently does not detect some cases of absence.