Hey Andrew,
thank you for your work!!
So one by one:
https://github.com/maiska/qubes-doc.rtd/commit/0b8529a026da0523355eec55c57c1da2aa110d07
By the way, with this one, the link is not actually broken. It still works, because your browser adds the missing forward slash automatically. Nonetheless, I've committed a fix to make it technically syntactically correct.
With the above commit there several links. I suppose you mean the internal one: it is so, yes, but for the convenience of my stupid script..., but let me explain:
Some people, when confronted with a problem, think
“I know, I'll use regular expressions.”
Now they have two problems.
Well.... :)
[...] other people's articles linking to the official Qubes OS documentation would be broken, since I do not think that there is a proxy to handle such requests and redirects? Or there is a simpler way?I don't understand why links would get broken. Let's use a concrete example to help me understand. Take this page, for example: https://www.qubes-os.org/doc/how-to-update/ After the migration to RtD, wouldn't this still be the same URL for that page? Why would it be any different? If you're saying it has to be a different URL for some reason, what would the new URL look like?
The new url when generated will look like:
foo.bar/user/how-to-guides/how-to-update.html from rst will look
like :doc:` foo </user/how-to-guides/how-to-update>`
Domain dependent or whatever...
Wouldn't converting all Markdown files to RST result in still using the _doc submodule, just with all the files converted? Maybe I'm not understanding something here.This could be a possibility yes, perhaps with a sphinx plugin for redirects. It exists, haven't tried it yet.Why only "a possibility"? I figured that would be the obvious thing to do, but clearly I am missing something. If there is a good reason to do otherwise, then that's totally fine! It's just not clear to me what that reason might be.
Nope, you are abs right!
My motivation behind this solution (meaning leave the docs as they are but empty etc.) was take it one step at a time w/o necessarily drain time in fixing possible broken links. Till the documentation is on RTD
and afterwards the website can be dealt with and properly cleared
of any redundant information (such as in _includes research.html,
cause i blank out translated it
into flat markdown or rst),
also than use the sphinx redirect extension, these all are nice to have and can be done afterwards.
The possibility was not the right word in this context...
The HCL and Downloads thus can be addressed later :)
About the pull requests I will look into it latest tomorrow, render and say if smth is 'missing'
One thing though which I did not think about:
The privacy policy should be 2x - one for the Qubes OS website, and one for RTD. The one for RTD should be adjusted and perhaps refer to also their privacy policy:
But maybe that's okay, since once we migrate to RtD, we'll no longer be relying on custom scripts like this to populate the table of contents.
Yes!! Hopefully there will be a lot less clutter :))
git clone -b new-master --recursive https://github.com/maiska/qubesos.github.io.rtd.git
So, how do I serve the site locally after doing this? Can you provide step-by-step instructions?
All the best,
m
On a fedora VM:
sudo dnf install ruby ruby-devel openssl-devel redhat-rpm-config @development-tools;
gem install jekyll bundler;
find . -name gem; #(in my case it was /home/user/.local/share/gem/)
git clone -b new-master --recursive https://github.com/maiska/qubesos.github.io.rtd.git; cd qubesos.github.io.rtd/
bundle config set --local path '/home/user/.local/share/gem/'
bundle install;
(if there is some sort of error with webrick, just try: bundle add webrick; bundle exec jekyll serve)
bundle exec jekyll serve
All the best,
m
--
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...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/d1d7a758-b879-4ee2-6ab7-e7ac92deaf04%40maiski.net.
Hi Marek,
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.
One question though:
have you had success with parsing admin-api.rst (as converted by pandoc from md?)
I get the error when parsing with docutils in order to post-process it for qubes:
docutils.utils.SystemMessage: /home/user/testingfilez/admin-api.rst:74: (SEVERE/4) Unexpected section title
and it cannot get over the table as it is...:/
all the best,
m
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 Tue, Nov 01, 2022 at 12:45:33PM +0100, mm wrote:
> Hi Marek, hi Andrew, hi Tobias,
> Marek, I merged your pull request, also merged your changes into master and
> added some enhancements and created a pull request.
> Here you could review it
> https://github.com/maiska/qubes-translation-utilz/pull/2
> Either way, one could try it out, there should be no more undefined or
> unknown label warnings when rendering the rst docs
> and thus could safely imho go and convert the documentation and host it on
> RTD.
> Here is a README.md instead of spamming via email
> https://github.com/maiska/qubes-translation-utilz/blob/master/README.md
> the configuration should be more readable also:
> https://github.com/maiska/qubes-translation-utilz/blob/master/md2rst/config.toml
> Please let me know if I have to fix further or this suffices.
Thanks. I'm a bit busy this and the next week, but maybe I'll manage to
take a look. Otherwise, after 11th of November.
All right.
Here is a preview: https://github.com/maiska/qubes-rst