[pve-devel] [PATCH docs 1/6] ceph: add anchors for use in troubleshooting section

[Alexander Zeidler]

On Tue Feb 4, 2025 at 10:52 AM CET, Max Carrara wrote:
> On Tue Feb 4, 2025 at 10:22 AM CET, Alexander Zeidler wrote:
>> On Mon Feb 3, 2025 at 5:19 PM CET, Max Carrara wrote:
>> > On Mon Feb 3, 2025 at 3:27 PM CET, Alexander Zeidler wrote:
>> >> Signed-off-by: Alexander Zeidler <a.zeidler at proxmox.com>
>> >> ---
>> >
>> > Some high-level feedback (see comments inline and in patches otherwise):
>> >
>> > - The writing style is IMO quite clear and straightforward, nice work!
>> Thank you for the review!
>>
>> >
>> > - In patch 03, the "_disk_health_monitoring" anchor reference seems to
>> >   break my build for some reason. Does this also happen on your end? The
>> >   single-page docs ("pve-admin-guide.html") seem to build just fine
>> >   otherwise.
>> Same for me, I will fix it.
>>
>> >
>> > - Regarding implicitly / auto-generated anchors, is it fine to break
>> >   those in general or not? See my other comments inline here.
>> >
>> > - There are a few tiny style things I personally would correct, but if
>> >   you disagree with them, feel free to leave them as they are.
>> I will look into it! Using longer link texts sounds good!
>>
>> >
>> > All in all this seems pretty solid; the stuff regarding the anchors
>> > needs to be clarified first (whether it's okay to break auto-generated
>> > ones & the one anchor that makes my build fail). Otherwise, pretty good!
>> See my two comments below.
>>
>> >
>> >>  pveceph.adoc | 8 ++++++++
>> >>  1 file changed, 8 insertions(+)
>> >>
>> >> diff --git a/pveceph.adoc b/pveceph.adoc
>> >> index da39e7f..93c2f8d 100644
>> >> --- a/pveceph.adoc
>> >> +++ b/pveceph.adoc
>> >> @@ -82,6 +82,7 @@ and vocabulary
>> >>  footnote:[Ceph glossary {cephdocs-url}/glossary].
>> >>  
>> >>  
>> >> +[[pve_ceph_recommendation]]
>> >>  Recommendations for a Healthy Ceph Cluster
>> >>  ------------------------------------------
>> >
>> > AsciiDoc automatically generated an anchor for the heading above
>> > already, and it's "_recommendations_for_a_healthy_ceph_cluster"
>> > apparently. So, there's no need to provide one here explicitly, since it
>> > already exists; it also might break old links that refer to the
>> > documentation.
>> For this I searched our forum before, it shows 12 results, the heading
>> was only added about a year ago. But apart from this specific anchor,
>> IMHO it can be okay to break such links in certain cases:
>>
>> * The main reasons for not using the auto generated ones are, that those
>>   are not stable (in case of changing the title) and can also be very
>>   long when using it with xref:...[...]. Such lines get even longer (and
>>   an awkward combined name) when using it as a prefix for sub sections
>>   (as often done).
>> * Since with the break there might have been added new or updated
>>   information in those chapters/sections, old forum posts may no longer
>>   be accurate anyway.
>> * In the Ceph chapter for example, we have been using the explicit
>>   "pve_ceph_" or "pveceph_" for years, so IMHO it should (almost
>>   always?) be added with adding a new section.
>>
>> >
>> > Though, perhaps in a separate series, you could look for all implicitly
>> > defined anchors and set them explicitly..? Not sure if that's something
>> > we want, though.
>> This would break a lot of links at the same time, so far I am not aware
>> about a notable benefit.
>>
>
> I agree with all of your points made here; so, all in all, great work!
> Ping me when you shoot out v2, then I'll have one last look. :)
v2: https://lore.proxmox.com/pve-devel/20250205100850.3-1-a.zeidler@proxmox.com/T/#t

>
>
>
> _______________________________________________
> pve-devel mailing list
> pve-devel at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel