search

OP-TEE / optee_docs

This git contains the official documentation for the OP-TEE project
BSD 2-Clause "Simplified" License
58 stars 96 forks source link

Using url for internal links #37

Closed vchong closed 5 years ago

vchong commented 5 years ago

Is it possible to use the full url rather than :ref:`page_name` for internal links as well in a page, specifically for aosp.rst, like this? This is to enhance portability, i.e. be able to use the page (.rst doc) as-is at a different location, e.g. github.com, etc.

A specific use case is when making an aosp release. The main release page (e.g. here) has a copy of aosp.rst (renamed as readme.rst) to capture the build instructions at the time. We don't/can't just point/link directly to aosp.rst itself since it's a moving target, i.e. updated to always reflects the current/latest build instructions.

If we use the page as-is right now, it would show up like here, i.e. the internal links using :ref:`page_name` show up literally and don't work.

jbech-linaro commented 5 years ago

Is it possible to use the full url rather than :ref:`page_name` for internal links as well in a page, specifically for aosp.rst, like this?

Yes, but I don't like it TBH. I think the solution to this issue is to

  1. remove the content on the "main release page" and simply add a redirection there to https://optee.readthedocs.io (/.../aosp.rst)
  2. Keep all release notes, build instructions at optee.readthedocs.io

We don't/can't just point/link directly to aosp.rst itself since it's a moving target, i.e. updated to always reflects the current/latest build instructions.

Why? What is moving? You mean that old instructions will be replaced and overwritten. I.e., old instructions gets lost? I see two solutions to that. Tag optee_docs just as we're tagging the other gits and/or add a second aosp-old.rst page that contains legacy instructions (I'd prefer just tags).

vchong commented 5 years ago

I see two solutions to that. Tag optee_docs just as we're tagging the other gits and/or add a second aosp-old.rst page that contains legacy instructions (I'd prefer just tags).

In that case, can you please tag 20441fe7928c30a5f5ffb4c6b22ef5262a15c42b as aosp-3.6.1 please? Thanks!

jbech-linaro commented 5 years ago

Done! https://github.com/OP-TEE/optee_docs/releases/tag/aosp-3.6.1

jbech-linaro commented 5 years ago

And I've enabled it in readthedocs also, so now this (https://optee.readthedocs.io/en/aosp-3.6.1/) will last "forever"

jforissier commented 5 years ago

And I've enabled it in readthedocs also, so now this (https://optee.readthedocs.io/en/aosp-3.6.1/) will last "forever"

:+1+ will you create a tag for each new OP-TEE release?

jbech-linaro commented 5 years ago

:+1+ will you create a tag for each new OP-TEE release?

Yes and I've also been thinking about adding optee_docs to our manifests, since I believe that would make tagging etc easier when doing releases.

jforissier commented 5 years ago

:+1+ will you create a tag for each new OP-TEE release?

Yes and I've also been thinking about adding optee_docs to our manifests, since I believe that would make tagging etc easier when doing releases.

Good idea IMO.

vchong commented 5 years ago

Thanks! Closing.