Hello Marek, hello Andrew,
I can have spare time starting Sunday to focus & reply.
(Please, Marek, recall that i have pointed out mid September that I am out off
the map
basically from 15.09 till 8.10.)
Nevertheless tried to fix different issues in some spare time, such as
embedding videos, toctree etc.
I will push my final version on master asap. (Still haven't gotten to the
PR/merge/refactor), suggest to wait till Sunday.
If that is not possible there are several issues to be considered:
0. please pay attention to config.toml and conf.py from master and the files in
preparation.
1. which rst files are to be copied (there are 3 atm, since the most issues
should be fixed via rstwriter2), which to be removed,
different extensions to be configured such as redirects (I suggest leaving an
empty hcl.rst (downloads etc) with a redirect, to be populated in a
later stage via jinja scripting), new strikeout extension and new role, video
directives, which markdown files are also to be copied
- is doc.md the right one etc? latex documents are rendered correctly (toctree
req)
2. !! Problem that should have a solution:
f.ex.https://qubes-doc-rst.readthedocs.io/en/latest/user/troubleshooting/installation-troubleshooting.html
in the sentence:
"Here are the steps to fix this. Note that this allows sys-net and sys-usb to take
complete control of the system, as described in the FAQ here:"
there should be a cross reference to FAQ VT-d iommu section but is not. (with
my version this is also a problem)
Unfortunately the documentation (sphinx referencing via roles, perhaps the
implementation?) is not saying anything how to handle punctuation with sections
and cross ref with ref,
so as of the moment I do not have an idea, apart from the basic stuff.
I also tried explicit automatic labeling above each section with a directive
(.. _id-of-section) - did not work out
3. different new files to be considered:
f.e.x 2 versions of the privacy content, how to edit the documentation - markdown
& rst version, visual style guide etc
4. what is done so far on master
-- video directives
-- toctree index, notes, schedules, upgrade, how to restore
-- section cross referencing small fixes
-- svg conversion to png for selected files and replacement in rst docs
-- convert leftover markdown links in rst files
-- markdown redirects
-- added directives for warning & note (can be used also for indicating
translated content)
-- anything i forgot
5. weblate - localization platform should be the way to go imho (sry not a big
fan of transifex rn, weblate is OS etc,
some more objective analysis will follow), there are several issues to be
clarified, wip, tails guys need good questions to work with
- will be done on sunday
6. anything i forgot, did not address, mentioned too briefly or not clarified i
will address on sun
(if it is still needed)
all the best,
m
On 10/2/22 18:24, Marek Marczykowski-Górecki wrote:
On Tue, Sep 27, 2022 at 01:15:56AM +0200, Marek Marczykowski-Górecki
wrote:
> On Mon, Sep 26, 2022 at 11:33:22PM +0200, mm wrote:
>> Hi Marek,
>>
>>
>> On 9/26/22 00:01, Marek Marczykowski-Górecki wrote:
>>> Hi M,
>>>
>>> In fact, I'm working on translation-utilz right now too. Marta
used her
>>> google-foo and found this gem:
>>> https://github.com/SamWilsn/docutils-rst-writer
>>>
>> this looks very nice!! :) Thanks Marta! :)
>>
>>> So, I replaced most of the qubesrstwriter2.py with just this thing and
>>> it's almost flawless (especially tables, images etc work out of the
>>> box).
>>
>> OK, thanks for the PR, I'll merge into and get rid of the obsolete
stuff
>> from my branch this days.
>>
>> I have some weird customized fixes all over, but this should work.
I spent some more time on polishing the converter (all pushed to the
same PR), and I think it's good enough already. There are few remaining
issues that Sphinx complains about, but at least some of them look like
issues already present in the original markdown files, and can be fixed
in the RST version manually. I'd prefer it this way (for this category
of issues), because Sphinx gives much better error reporting than
jekyll, so it's easier to iterate.
The rendered content can be seen at
https://qubes-doc-rst.readthedocs.io/en/latest/
And the converted source at
https://github.com/marmarek/qubes-doc/tree/work3/
Note the above has already enabled PDF+ePUB version, and German and
Spanish translations (although most content is not translated yet).
I did also used your markdownredirector to generate redirects to RTD,
here:
https://github.com/QubesOS/qubes-doc/pull/1272
It's deployed to wwwpreview.qubes-os.org. It works for most links, for
example
https://wwwpreview.qubes-os.org/doc/secondary-storage/
But, htmlproofer complains about links to specific sections - which
indeed are broken now ('#' part does not survive redirect). For example:
https://wwwpreview.qubes-os.org/doc/#troubleshooting
I don't think that's a big issue in practice, but will require adjusting
htmlproofer call.
Anyway, I see further steps as:
1. Review and merge (or reject) current PRs to qubes-doc. They will
become completely obsolete after conversion. Some of them are waiting
for my feedback...
2. Convert the whole qubes-doc repo to ReST format, and connect to
readthedocs.org as doc.qubes-os.org (any better idea for the domain?)
3. Disconnect qubes-doc submodule from qubesos.github.io repo, and
replace with generated redirects (the content of PR 1272 above).
4. Incrementally fix remaining issues in rst files (at this point, I
don't see any critical ones). Some I see Maya fixed already in the
fixed-rst-errors dir.
5. Adjust documentation contributing guidelines for the new format (this
page actually has rst format issues after conversion, but I haven't
bothered to fix them, because the content would need significant change
anyway).
And then, translation-related:
6. Cleanup our transifex project (remove previous attempts, like
doc-related markdown files)
7. Upload rst version (already done, but will need re-uploading after
final conversion).
8. Setup CI job to pull translations to qubes-translated repo (it's a
single transifex client call, I already have it ready to go from
previous attempt).
9. Adjust theme on translated pages to include warning that non-English
version may be less accurate.
10. Write/Adjust guidelines for translators, open transifex project
again.
The above might get adjusted, if we'd like to use weblate instead, but I
think that's separate discussion (both in practice require migration to
rst first).
There is also a topic of translating the website itself, which IMO will
become much easier once documentation is moved away.
--
You received this message because you are subscribed to the Google Groups
"qubes-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to qubes-devel+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/qubes-devel/053dbf0c-2478-ec0c-395f-b797f3e96c7c%40maiski.net.
