Relocation of the documention (final solution) #50466

Closed
opened 2017-01-18 22:20:27 +01:00 by Aaron Carlisle · 54 comments
Member

Currently, our documentation is all over the place:

And we are not following this industry standard of having one place to have all the documentation.

I purpose that we move documentation to this base URL: docs.blender.org

from there we can move the documentation:

This would allow us to separate its integration on blender.org and move it to its own jail

Most of the change can happen right away and will not affect users, for we can setup redirects.
The biggest change is that we need to design a home page for docs.blender.org


Aside from this documentation from other projects should be added to the rBM?

Currently, our documentation is all over the place: - https://www.blender.org/api/ - https://www.blender.org/manual/ - ftp://ftp.blender.org/ideasman42/bam_docs/index.html And we are not following this industry standard of having one place to have all the documentation. I purpose that we move documentation to this base URL: docs.blender.org from there we can move the documentation: - https://www.docs.blender.org/api/ - https://www.docs.blender.org/manual/ - https://www.docs.blender.org/bam/ This would allow us to separate its integration on blender.org and move it to its own [jail ](https://en.wikipedia.org/wiki/FreeBSD_jail) Most of the change can happen right away and will not affect users, for we can setup redirects. The biggest change is that we need to design a home page for docs.blender.org ------------------------------- Aside from this documentation from other projects should be added to the rBM?
Author
Member

Changed status to: 'Open'

Changed status to: 'Open'
Author
Member

Added subscribers: @Blendify, @fsiddi, @dmcgrath, @Ton

Added subscribers: @Blendify, @fsiddi, @dmcgrath, @Ton
Member

Added subscriber: @JohnRoper

Added subscriber: @JohnRoper
Member

I would be willing to design a home page for it using the Blender web assets.

I would be willing to design a home page for it using the Blender web assets.
Author
Member

That would be helpful thank you John

That would be helpful thank you John
Member

Here is the design I am working on. #50467

Here is the design I am working on. #50467
Member

The idea has been floating around for a while (I think possible from Campbell and I discussing it?). Either way, I am obviously for the idea. A bit of the reasons I had last we discussed were security related more than anything. Here are some of the valid points that I could find that we've discussed in the past already, to try bring things into one place for us:

#blenderwiki.2016-06-23: 12:04:10 < Blendify> troubled why does the manual have /en ?
#blenderwiki.2016-06-23: 12:20:14 < troubled> Blendify: because it's english?
#blenderwiki.2016-06-23: 12:20:16 < troubled> :)
#blenderwiki.2016-06-23: 12:21:20 < Blendify> but b.org/manual is english and nothing links b.org/manual/en
#blenderwiki.2016-06-23: 12:21:52 < troubled> https://www.blender.org/manual/ is english
#blenderwiki.2016-06-23: 12:22:19 < troubled> i think /en was possibly a symlink or something too, ie: /manual/en/ is identical to /manual/
#blenderwiki.2016-06-23: 12:24:40 < Blendify> they are slightly different
#blenderwiki.2016-06-23: 12:25:08 < Blendify> wait.. never mind... outdated cache
#blenderwiki.2016-06-23: 12:25:13 < troubled> probably ya
#blenderwiki.2016-06-23: 12:25:21 < troubled> i know we don't build en twice or anything
#blenderwiki.2016-06-23: 12:25:57 < troubled> ideally we should be moving off of /manual. That is very bad if were going to shard up the name space into / and eventually /
#blenderwiki.2016-06-23: 12:27:20 < troubled> tbh /manual should be some sort of landing page with links to the langs, sorta like landing page for wikipedia.org or similar
#blenderwiki.2016-06-23: 12:27:31 < Blendify> .
#blenderwiki.2016-06-23: 12:27:42 < troubled> it was a known mistake to not do // from the start

#blenderwiki.2016-12-11: 12:11:54 < troubled> also, our manual zip files should have lang and version/rev info in the files names or something :/
#blenderwiki.2016-12-11: 12:12:06 < troubled> at least language distinction
#blenderwiki.2016-12-11: 12:12:23 < troubled> otherwise you never know what version of the manual your zip actually is from

#blenderwiki.2016-12-11: 14:08:30 < troubled> anyway, i figure we could redo the urls a bit and make it so /manual/ is some sort of multilingual landing page, and then have /manual/// etc
#blenderwiki.2016-12-11: 14:08:47 < troubled> kinda tricky to test when all we have is a live site though
#blenderwiki.2016-12-11: 14:09:29 <@Blendify> I think it should be /manual//

#blenderwiki.2016-12-11: 14:10:38 < troubled> also wondering if we should move to manual.blender.org instead of hanging stuff off blender.org
#blenderwiki.2016-12-11: 14:10:52 < troubled> namely for security/xss/cookie/etc issues
#blenderwiki.2016-12-11: 14:11:26 < troubled> than we can at least separate things a bit, and allow us to run it somewhere other than the main www site
#blenderwiki.2016-12-11: 14:11:38 < troubled> atm its kinda tightly coupled to www.b.o/
#blenderwiki.2016-12-11: 14:12:03 < troubled> something to think about at least
#blenderwiki.2016-12-11: 14:14:28 <@Blendify> hmm... ok

#blenderwiki.2016-12-13: 11:26:11 <@Blendify> troubled, for the docs and redoing to URL what about something like docs.blender.org/manual ?
#blenderwiki.2016-12-13: 11:26:47 <@Blendify> and docs.blender.org/manual
#blenderwiki.2016-12-13: 11:27:01 <@Blendify> err... docs.blender.org/api

#blenderwiki.2016-12-13: 14:09:15 < troubled> Blendify: whatever makes the most sense i guess. i have no strong opinions, but your idea looks great so far
#blenderwiki.2016-12-13: 14:09:47 < troubled> best we put good thought into it though so that its one last time
#blenderwiki.2016-12-13: 14:10:00 <@Blendify> yep
#blenderwiki.2016-12-13: 14:10:44 <@Blendify> docs.blender.org could have a nice landing page that can include may docs
#blenderwiki.2016-12-13: 14:10:56 <@Blendify> api, manual, bam, ect...
#blenderwiki.2016-12-13: 14:14:30 < troubled> ya, makes the most sense
#blenderwiki.2016-12-13: 14:15:24 < troubled> we can set up the vhost and stuff in advance too for testing
#blenderwiki.2016-12-13: 14:16:08 <@Blendify> https://www.blender.org/api/ needs to be cleaned up
#blenderwiki.2016-12-13: 14:16:29 < troubled> ill have to take a look at our ip situation though. would be nice to give it its own dedicated jail for this, but worst case can just toss in with www i guess
#blenderwiki.2016-12-13: 14:16:57 < troubled> its a pretty old dir that api
#blenderwiki.2016-12-13: 14:17:26 <@Blendify> https:*www.blender.org/api/htmlI/ and https:*www.blender.org/api/htmlII/ need a home
#blenderwiki.2016-12-13: 14:17:51 < troubled> bit of legacy urls in there. dont want to just remove too much stuff without looking for 404s for redirects etc though
#blenderwiki.2016-12-13: 14:19:11 < troubled> i can probably compile an anonymous (ips stripped) report of all access to the api path that arent 200s or such for us too since our access logs are retained indefinetly
#blenderwiki.2016-12-13: 14:19:45 <@Blendify> Some stuff there dates back to the year 2000

As you can see, we have a few other things to consider aside from the domain, such as versioning.

The idea has been floating around for a while (I think possible from Campbell and I discussing it?). Either way, I am obviously for the idea. A bit of the reasons I had last we discussed were security related more than anything. Here are some of the valid points that I could find that we've discussed in the past already, to try bring things into one place for us: > #blenderwiki.2016-06-23: 12:04:10 < Blendify> troubled why does the manual have /en ? > #blenderwiki.2016-06-23: 12:20:14 < troubled> Blendify: because it's english? > #blenderwiki.2016-06-23: 12:20:16 < troubled> :) > #blenderwiki.2016-06-23: 12:21:20 < Blendify> but b.org/manual is english and nothing links b.org/manual/en > #blenderwiki.2016-06-23: 12:21:52 < troubled> https://www.blender.org/manual/ is english > #blenderwiki.2016-06-23: 12:22:19 < troubled> i think /en was possibly a symlink or something too, ie: /manual/en/ is identical to /manual/ > #blenderwiki.2016-06-23: 12:24:40 < Blendify> they are slightly different > #blenderwiki.2016-06-23: 12:25:08 < Blendify> wait.. never mind... outdated cache > #blenderwiki.2016-06-23: 12:25:13 < troubled> probably ya > #blenderwiki.2016-06-23: 12:25:21 < troubled> i know we don't build en twice or anything > #blenderwiki.2016-06-23: 12:25:57 < troubled> ideally we should be moving off of /manual. That is very bad if were going to shard up the name space into /<lang> and eventually /<version> > #blenderwiki.2016-06-23: 12:27:20 < troubled> tbh /manual should be some sort of landing page with links to the langs, sorta like landing page for wikipedia.org or similar > #blenderwiki.2016-06-23: 12:27:31 < Blendify> . > #blenderwiki.2016-06-23: 12:27:42 < troubled> it was a known mistake to not do /<lang>/<ver> from the start > #blenderwiki.2016-12-11: 12:11:54 < troubled> also, our manual zip files should have lang and version/rev info in the files names or something :/ > #blenderwiki.2016-12-11: 12:12:06 < troubled> at least language distinction > #blenderwiki.2016-12-11: 12:12:23 < troubled> otherwise you never know what version of the manual your zip actually is from > #blenderwiki.2016-12-11: 14:08:30 < troubled> anyway, i figure we could redo the urls a bit and make it so /manual/ is some sort of multilingual landing page, and then have /manual/<lang>/<ver>/ etc > #blenderwiki.2016-12-11: 14:08:47 < troubled> kinda tricky to test when all we have is a live site though > #blenderwiki.2016-12-11: 14:09:29 <@Blendify> I think it should be /manual/<ver>/<lang> > #blenderwiki.2016-12-11: 14:10:38 < troubled> also wondering if we should move to manual.blender.org instead of hanging stuff off blender.org > #blenderwiki.2016-12-11: 14:10:52 < troubled> namely for security/xss/cookie/etc issues > #blenderwiki.2016-12-11: 14:11:26 < troubled> than we can at least separate things a bit, and allow us to run it somewhere other than the main www site > #blenderwiki.2016-12-11: 14:11:38 < troubled> atm its kinda tightly coupled to www.b.o/ > #blenderwiki.2016-12-11: 14:12:03 < troubled> something to think about at least > #blenderwiki.2016-12-11: 14:14:28 <@Blendify> hmm... ok > #blenderwiki.2016-12-13: 11:26:11 <@Blendify> troubled, for the docs and redoing to URL what about something like docs.blender.org/manual ? > #blenderwiki.2016-12-13: 11:26:47 <@Blendify> and docs.blender.org/manual > #blenderwiki.2016-12-13: 11:27:01 <@Blendify> err... docs.blender.org/api > #blenderwiki.2016-12-13: 14:09:15 < troubled> Blendify: whatever makes the most sense i guess. i have no strong opinions, but your idea looks great so far > #blenderwiki.2016-12-13: 14:09:47 < troubled> best we put good thought into it though so that its one last time > #blenderwiki.2016-12-13: 14:10:00 <@Blendify> yep > #blenderwiki.2016-12-13: 14:10:44 <@Blendify> docs.blender.org could have a nice landing page that can include may docs > #blenderwiki.2016-12-13: 14:10:56 <@Blendify> api, manual, bam, ect... > #blenderwiki.2016-12-13: 14:14:30 < troubled> ya, makes the most sense > #blenderwiki.2016-12-13: 14:15:24 < troubled> we can set up the vhost and stuff in advance too for testing > #blenderwiki.2016-12-13: 14:16:08 <@Blendify> https://www.blender.org/api/ needs to be cleaned up > #blenderwiki.2016-12-13: 14:16:29 < troubled> ill have to take a look at our ip situation though. would be nice to give it its own dedicated jail for this, but worst case can just toss in with www i guess > #blenderwiki.2016-12-13: 14:16:57 < troubled> its a pretty old dir that api > #blenderwiki.2016-12-13: 14:17:26 <@Blendify> https:*www.blender.org/api/htmlI/ and https:*www.blender.org/api/htmlII/ need a home > #blenderwiki.2016-12-13: 14:17:51 < troubled> bit of legacy urls in there. dont want to just remove too much stuff without looking for 404s for redirects etc though > #blenderwiki.2016-12-13: 14:19:11 < troubled> i can probably compile an anonymous (ips stripped) report of all access to the api path that arent 200s or such for us too since our access logs are retained indefinetly > #blenderwiki.2016-12-13: 14:19:45 <@Blendify> Some stuff there dates back to the year 2000 As you can see, we have a few other things to consider aside from the domain, such as versioning.

After some considerations, here is what we can do:

  • create the docs.blender.org domain
  • move /api and /manual there, see below for versioning and language support
  • reference dev docs and pipeline docs
  • no BAM (it's still in development, and the relevant parts have been documented in the pipeline section of the manual)
docs.blender.org
        /index.html                     Serve the content shown on www.blender.org/docs
        /api                            Redirect to the latest API (requires update on release)
        /api/<version>/
        /manual                         Redirect to the latest EN manual (requires update on release)
        /manual/<lang>/<version>/       We use <lang>/<version> because it's fairly standard

The mockup made by @JohnRoper is nice, and we are likely going to implement it directly within blender.org

This involves several steps and is mostly backend work. High priority is to keep all existing links working. More discussion can happen in #blenderwiki

After some considerations, here is what we can do: * create the docs.blender.org domain * move /api and /manual there, see below for versioning and language support * reference dev docs and pipeline docs * no BAM (it's still in development, and the relevant parts have been documented in the pipeline section of the manual) ``` docs.blender.org /index.html Serve the content shown on www.blender.org/docs /api Redirect to the latest API (requires update on release) /api/<version>/ /manual Redirect to the latest EN manual (requires update on release) /manual/<lang>/<version>/ We use <lang>/<version> because it's fairly standard ``` The mockup made by @JohnRoper is nice, and we are likely going to implement it directly within blender.org This involves several steps and is mostly backend work. High priority is to keep all existing links working. More discussion can happen in #blenderwiki
Member

So far I have the following things done for this task:

  • www.docs.blender.org and docs.blender.org DNS setup
  • LetsEncrypt certificate registered for www.docs.b.o and docs.b.o
  • HTTP will redirect to HTTPS, as well as enable HSTS
  • Simple index.html for https://docs.blender.org/ with listing for /api/ and /manual/
  • /api/ continues to have Indexing enabled instead of redirecting, which would hide the available choices
  • /manual/ should redirect to /manual//
  • /manual// should then redirect to /manual//dev/ which is the latest version of the manual (ie: trunk)
  • /manual/ has a simple index.html file in place, as well as Indexing disabled to prevent browsing
  • https:*docs.blender.org/robots.txt and https:*docs.blender.org/favicon.ico were created

I spoke with mont29 in IRC and had him update his script paths for /api/, so all new updates should go to the live version at https:*docs.blender.org/api/ with the old location at https:*www.blender.org/api/ being a stale copy. At some point when we are "ready", this old location will be replaced with redirects to the new location. The same will happen with the /manual/ path, but since it is an automated script, it's not a big deal to serve both locations.

So far I have the following things done for this task: - www.docs.blender.org and docs.blender.org DNS setup - LetsEncrypt certificate registered for www.docs.b.o and docs.b.o - HTTP will redirect to HTTPS, as well as enable HSTS - Simple index.html for https://docs.blender.org/ with listing for /api/ and /manual/ - /api/ continues to have Indexing enabled instead of redirecting, which would hide the available choices - /manual/<lang> should redirect to /manual/<lang>/ - /manual/<lang>/ should then redirect to /manual/<lang>/dev/ which is the latest version of the manual (ie: trunk) - /manual/ has a simple index.html file in place, as well as Indexing disabled to prevent browsing - https:*docs.blender.org/robots.txt and https:*docs.blender.org/favicon.ico were created I spoke with mont29 in IRC and had him update his script paths for /api/, so all new updates should go to the live version at https:*docs.blender.org/api/ with the old location at https:*www.blender.org/api/ being a stale copy. At some point when we are "ready", this old location will be replaced with redirects to the new location. The same will happen with the /manual/ path, but since it is an automated script, it's not a big deal to serve both locations.
Member

@dmcgrath @fsiddi If you can give me the info or create a new repository here for me I can upload the code for my design for the homepage.

@dmcgrath @fsiddi If you can give me the info or create a new repository here for me I can upload the code for my design for the homepage.
Member

Added subscriber: @Sergey

Added subscriber: @Sergey
Member

In #50466#413130, @JohnRoper wrote:
@dmcgrath @fsiddi If you can give me the info or create a new repository here for me I can upload the code for my design for the homepage.

That is something that @Sergey deals with afaik, but maybe you could just use github in the meantime?

Just curious, but was this html for the docs.blender.org landing page? Or something else?

> In #50466#413130, @JohnRoper wrote: > @dmcgrath @fsiddi If you can give me the info or create a new repository here for me I can upload the code for my design for the homepage. That is something that @Sergey deals with afaik, but maybe you could just use github in the meantime? Just curious, but was this html for the docs.blender.org landing page? Or something else?
Member

yes. It is just html code

yes. It is just html code
Member

@JohnRoper so where is the code? I was hoping to at least get it in place :p

@JohnRoper so where is the code? I was hoping to at least get it in place :p

Here is some code @dmcgrath https://github.com/armadillica/docs.blender.org

We can decide what to do with this repo later on (maybe can be part of something larger).

Here is some code @dmcgrath https://github.com/armadillica/docs.blender.org We can decide what to do with this repo later on (maybe can be part of something larger).
Member

Cool, thanks! I put it in place. Probably could use similar for /manual/ and /api/ I guess, but /api/ would be tricky just cause of all the links.

Anyway, looks great, thanks! o/

Cool, thanks! I put it in place. Probably could use similar for /manual/ and /api/ I guess, but /api/ would be tricky just cause of all the links. Anyway, looks great, thanks! o/
Member

@fsiddi @dmcgrath Code added to that github (pull request)

@fsiddi @dmcgrath Code added to that github (pull request)
Author
Member

Looks great guys! I think that the docs.blender.org should also be added to the header bar. Any thoughts? This would give the docs more traffic.

Looks great guys! I think that the docs.blender.org should also be added to the header bar. Any thoughts? This would give the docs more traffic.
Member

Thanks @JohnRoper, but that is controlled by Francesco I think. I would probably also suggest using .html as the extension, as opposed to .htm so we don't have to fiddle with the DirectoryIndex configuration.

@Blendify I would probably hold off adding anything to the header on the other sites until it is official "live". Speaking of which, I guess we can think about actually switching things soon?

Thanks @JohnRoper, but that is controlled by Francesco I think. I would probably also suggest using .html as the extension, as opposed to .htm so we don't have to fiddle with the DirectoryIndex configuration. @Blendify I would probably hold off adding anything to the header on the other sites until it is official "live". Speaking of which, I guess we can think about actually switching things soon?
Member

@fsiddi Oh, I almost forgot, but that index.htm file also has a blender.org Google Analytics id. Not sure if that was intended.

@fsiddi Oh, I almost forgot, but that index.htm file also has a blender.org Google Analytics id. Not sure if that was intended.
Member

Added subscriber: @Tobias

Added subscriber: @Tobias
Member

I absolutely see no need for a landing page (https://docs.blender.org/manual/)

  • From a UX point of view every single click counts. (support > docs > landing >)
  • The majority of readers don't need this page.
  • No other doc. (I know) use one (not an argument, but a hint).
  • Versioning will bring another way to switch langs.
  • The count of individual languages isn't high enough and not going to rise.
  • The translation user count according to GAnalytics is as expected (even if the percentage is low)

I would suggest to rather:

  • Redesign: content.html (back to full lang. name).
  • Add a dedicated translation link that leads to landing page (bypass).
  • Add translation links as a list directly to the docs page (manual box).
I absolutely see no need for a landing page (https://docs.blender.org/manual/) - From a UX point of view every single click counts. (support > docs > landing >) - The majority of readers don't need this page. - No other doc. (I know) use one (not an argument, but a hint). - Versioning will bring another way to switch langs. - The count of individual languages isn't high enough and not going to rise. - The translation user count according to GAnalytics is as expected (even if the percentage is low) I would suggest to rather: - Redesign: content.html (back to full lang. name). - Add a dedicated translation link that leads to landing page (bypass). - Add translation links as a list directly to the docs page (manual box).
Author
Member

I think we should add something like read the docs. I have looked into but have had a hard time being able to port it to our setup.

I think we should add something like read the docs. I have looked into but have had a hard time being able to port it to our setup.
Member

In #50466#413374, @Tobias wrote:
I absolutely see no need for a landing page (https://docs.blender.org/manual/)

That's fine by me, as it saves worrying about a landing page. But where should we redirect people that visit /manual/? I can assume that we would default them to /manual/en/ via a temp 302 redirect, which in turn will redirect to /manual/en/dev/? I think that last one is a 301 atm, but I can change that to a 302 so it at least allows us to change it quickly to something else, down the road.

> In #50466#413374, @Tobias wrote: > I absolutely see no need for a landing page (https://docs.blender.org/manual/) That's fine by me, as it saves worrying about a landing page. But where should we redirect people that visit /manual/? I can assume that we would default them to /manual/en/ via a temp 302 redirect, which in turn will redirect to /manual/en/dev/? I think that last one is a 301 atm, but I can change that to a 302 so it at least allows us to change it quickly to something else, down the road.
Member

Added subscriber: @JulianEisel

Added subscriber: @JulianEisel
Member

In general I'm a big fan of gathering all our services on more centralized places, making it easier to find and access them. So big +1 for the idea of bringing all the docs to a unified docs.blender.org domain.

The way we currently deliver docs is a mess - especially those on the wiki. So I'd really like to see some solid planning on how to organize things before we move forward.
Main reason I'm saying that is because the wiki wasn't mentioned here yet, and I think it should align well with the plans discussed here. We should either move it to docs.blender.org too, or agree to keep it separate on wiki.blender.org - at the cost of breaking the rule of a centralized location for docs. (Also see #48096.)

Another thing I'm quite vary about: /api/ is pretty misleading here. What we are talking about is the Blender Python API (BPY API), Blender has many more APIs (mainly in C/C++ code). A docs.blender.org/api/ page would be a quite nice trap for people searching for C/C++ code docs.
Two things we could do:

  • Use something like docs.blender.org/python_api/ instead
  • Add online C/C++ code API docs to docs.blender.org/api/. These would likely be automatically generated docs using [Doxygen ]]. We already use markup comments for it everywhere in code and I know that various people actually generate API docs from this (check this old [http:*www.letworyinteractive.com/blendercode/modules.html | 2.61 example ).

I actually lean towards the second one, even if that means more work and increased maintenance burden once again. It would be interesting to see if such docs help people getting into the source code.

In general I'm a big fan of gathering all our services on more centralized places, making it easier to find and access them. So big +1 for the idea of bringing all the docs to a unified docs.blender.org domain. The way we currently deliver docs is a mess - especially those on the wiki. So I'd really like to see some solid planning on how to organize things before we move forward. Main reason I'm saying that is because the wiki wasn't mentioned here yet, and I think it should align well with the plans discussed here. We should either move it to docs.blender.org too, or agree to keep it separate on wiki.blender.org - at the cost of breaking the rule of a centralized location for docs. (Also see #48096.) Another thing I'm quite vary about: `/api/` is pretty misleading here. What we are talking about is the Blender Python API (BPY API), Blender has many more APIs (mainly in C/C++ code). A `docs.blender.org/api/` page would be a quite nice trap for people searching for C/C++ code docs. Two things we could do: * Use something like `docs.blender.org/python_api/` instead * Add online C/C++ code API docs to `docs.blender.org/api/`. These would likely be automatically generated docs using [Doxygen ]]. We already use markup comments for it everywhere in code and I know that various people actually generate API docs from this (check this old [[http:*www.letworyinteractive.com/blendercode/modules.html | 2.61 example ](http:*www.stack.nl/~dimitri/doxygen/)). I actually lean towards the second one, even if that means more work and increased maintenance burden once again. It would be interesting to see if such docs help people getting into the source code.
Author
Member

@JulianEisel I think that that is a good idea

@JulianEisel I think that that is a good idea
Member

Added subscriber: @mont29

Added subscriber: @mont29
Member

Not sure I like /python_api/ much, just for url neatness. I think something like /python/api/ or similar looks better than having hyphens and underscores in the URL.

Today I activated the redirect from https:*www.blender.org/api/ to https:*docs.blender.org/api/. As of now, we are "live" for API docs (@mont29 was already set to update the new location, might as well make it active).

I also added a HEADER.html and FOOTER.html to the docs.blender.org git repo that is used to wrap the directory listing at https://docs.blender.org/api/ in the current blender theme. It needs some CSS love, but perhaps @fsiddi would be better off handling this as it is his theme. Just give me a poke when you need the repo on the webserver updated.

Not sure I like /python_api/ much, just for url neatness. I think something like /python/api/ or similar looks better than having hyphens and underscores in the URL. Today I activated the redirect from https:*www.blender.org/api/ to https:*docs.blender.org/api/. As of now, we are "live" for API docs (@mont29 was already set to update the new location, might as well make it active). I also added a HEADER.html and FOOTER.html to the docs.blender.org git repo that is used to wrap the directory listing at https://docs.blender.org/api/ in the current blender theme. It needs some CSS love, but perhaps @fsiddi would be better off handling this as it is his theme. Just give me a poke when you need the repo on the webserver updated.

@JulianEisel please let’s not start calling all and everything 'API'!

Blender does not have any C api really, an API would imply Blender can be used as a library, or use some kind of runtime-loadable C/C++ plugins, which it cannot (and we do not seek anything like that currently). Even though it would be great to document more our code structure etc., this is no API at all (or, you can call it private APIs if you want), and imho does not pertain to docs area, more to dev one. The same goes with C++ of course.

To summarize my point: let’s not document Blender’s source code into docs namespace, imho it does not pertain here, but in dev namespace.

@JulianEisel please let’s not start calling all and everything 'API'! Blender does not have any C api really, an API would imply Blender can be used as a library, or use some kind of runtime-loadable C/C++ plugins, which it cannot (and we do not seek anything like that currently). Even though it would be great to document more our code structure etc., this is no API at all (or, you can call it private APIs if you want), and imho does not pertain to `docs` area, more to `dev` one. The same goes with C++ of course. To summarize my point: let’s not document Blender’s source code into `docs` namespace, imho it does not pertain here, but in `dev` namespace.
Member

I made a quick sitemap and updated the robots file

Both were added to the git repo. Same update poke me rules apply :)

As well, the old https:*www.blender.org/manual/ paths now redirect to https:*docs.blender.org/manual/. The blender code and existing manual links should be updated and the old path considered defunct.

I made a quick sitemap and updated the robots file - https://docs.blender.org/robots.txt - https://docs.blender.org/sitemap.xml Both were added to the git repo. Same update poke me rules apply :) As well, the old https:*www.blender.org/manual/ paths now redirect to https:*docs.blender.org/manual/. The blender code and existing manual links should be updated and the old path considered defunct.

Thanks for all the replies and inputs! Here is a summary:

  • we keep /api for the python API (there will be no other API in the foreseeable future)
  • we tweak CSS for the dir lists as suggested
  • manual will get versioning and lang switch (in RTD style) soon

Here is a further discussion point: to make API urls more friendly I would consider the follow structure /api/<version>/, for example:

/api/2.71a
/api/2.71
/api/2.71rc1
/api/2.71rc1

All existing links should redirect correctly, so this is potentially quite some work. Just wanna bring it up because a more semantic numbering would be nice. @dmcgrath do you think this is doable?

Thanks for all the replies and inputs! Here is a summary: - we keep `/api` for the python API (there will be no other API in the foreseeable future) - we tweak CSS for the dir lists as suggested - manual will get versioning and lang switch (in RTD style) soon Here is a further discussion point: to make API urls more friendly I would consider the follow structure `/api/<version>/`, for example: `/api/2.71a` `/api/2.71` `/api/2.71rc1` `/api/2.71rc1` All existing links should redirect correctly, so this is potentially quite some work. Just wanna bring it up because a more semantic numbering would be nice. @dmcgrath do you think this is doable?
Member

Hey @fsiddi

I assume that you are the CSS guru of the group, and was hoping that we could take care of tweaks to the CSS for the /api path together? Of course I am here to get the changes live and tested with you! Let me know when you want to get together and knock it out of the park, etc.

The /api/<version>/ stuff is up to the developers, IMHO; I have no dogs in this fight. Ideally I think the actual naming should be something the core developers chime in on though, not me. My only advice is to do it so that it matches existing file and directory naming conventions, but I don't know what conventions you are. Were you proposing to change existing filenames and set up redirects? Or just do this for new directories? If anything, @mont29 could setup symlinks for existing directories to allow old and new locations to exist, and save any work at all on the back end. Then just make sure that new stuff adhears to the new standard. Thoughts?

If you must move stuff, I can work with @mont29 to ease some of the rsync stuff by working lockstep with him to rename paths on the shell so that he doesn't have to re-upload hundreds of megabytes again for something that just changed paths, but it should be him to make the change or else he will just blow away all of the work done on the server side.Plus he is the actual maintainer of the /api stuff, I think?

Hey @fsiddi I assume that you are the CSS guru of the group, and was hoping that we could take care of tweaks to the CSS for the `/api` path together? Of course I am here to get the changes live and tested with you! Let me know when you want to get together and knock it out of the park, etc. The `/api/<version>/` stuff is up to the developers, IMHO; I have no dogs in this fight. Ideally I think the actual naming should be something the core developers chime in on though, not me. My only advice is to do it so that it matches existing file and directory naming conventions, but I don't know what conventions you are. Were you proposing to change existing filenames and set up redirects? Or just do this for new directories? If anything, @mont29 could setup symlinks for existing directories to allow old and new locations to exist, and save any work at all on the back end. Then just make sure that new stuff adhears to the new standard. Thoughts? If you must move stuff, I can work with @mont29 to ease some of the rsync stuff by working lockstep with him to rename paths on the shell so that he doesn't have to re-upload hundreds of megabytes again for something that just changed paths, but it should be him to make the change or else he will just blow away all of the work done on the server side.Plus he is the actual maintainer of the `/api` stuff, I think?
Author
Member

I talked to Campbell and we decided that there is no need for subversions of the API. We should follow this layout:

I talked to Campbell and we decided that there is no need for subversions of the API. We should follow this layout: - https://docs.blender.org/api/dev/ for daily builds (to match the scheme for the manual) - https://docs.blender.org/api/current/ always redirects (or symlink) to latest release - https://docs.blender.org/api/2_78a/ for old/current releases releases
Member

@Blendify out of curiosity, why the underscore? Is that common practice for versioning, in blender or anywhere else?

@Blendify out of curiosity, why the underscore? Is that common practice for versioning, in blender or anywhere else?
Author
Member

Not really but do not like https:*docs.blender.org/api/278a/ a guess we could also do https:*docs.blender.org/api/2.78a/ but I do not know if servers and other os's like that.

Not really but do not like https:*docs.blender.org/api/278a/ a guess we could also do https:*docs.blender.org/api/2.78a/ but I do not know if servers and other os's like that.
Member

Well, as I said before, up to you guys. The server shouldn't care about a period in the path for a directory though, just an FYI.

Well, as I said before, up to you guys. The server shouldn't care about a period in the path for a directory though, just an FYI.

Dots in file/dir names are not an issue on Unix since ages ;)

Agree name should be made simpler, how exactly is not that important imho, as long as it can be easily used in automated processes?

Regarding current (daily build) API, I would rather use branches names (as currently, so https://docs.blender.org/api/master/ ), also because we may want other branches's API doc at some point (thinking about blender2.8 here for near future) - and find it clearer what is documenting what that way.

@dmcgrath would definitively rather use symlinks, than renaming all dirs here (and doing some redirects on server side), sounds much, much simpler. :)

Dots in file/dir names are not an issue on Unix since ages ;) Agree name should be made simpler, how exactly is not that important imho, as long as it can be easily used in automated processes? Regarding current (daily build) API, I would rather use branches names (as currently, so https://docs.blender.org/api/master/ ), also because we may want other branches's API doc at some point (thinking about blender2.8 here for near future) - and find it clearer what is documenting what that way. @dmcgrath would definitively rather use symlinks, than renaming all dirs here (and doing some redirects on server side), sounds much, much simpler. :)
Member

I think he meant more like a server treating something like foo.blah as some weird extension in Apache using some weird mime type or extension handler. At least that is what I took away from it.

Glad to hear @mont29. Anything that saves us from having to micromanage a bazillion files is good in my book :)

I think he meant more like a server treating something like `foo.blah` as some weird extension in Apache using some weird mime type or extension handler. At least that is what I took away from it. Glad to hear @mont29. Anything that saves us from having to micromanage a bazillion files is good in my book :)
Member

@mont29, my point is simply that docs.blender.org/api/ is far too vague and may be misleading. We do have many APIs, it doesn't matter if they're internal/private or external. The thing is, one person clicking on docs.blender.org/api/ might expect to see an API documentation for C/C++ plugins, another one might expect to see the documentation of the internal APIs and another one might expect it to show the Python API documentation.
The URLs and sitemap structure should make it clear what kind of APIs and corresponding docs are available.


Also, please consider my point regarding the Wiki. Why should all docs except of Blender core development ones be on docs.blender.org ? If there are good reasons for it, I'd be fine with leaving them in the wiki, but ideally we'd have a central place for all documentation - manual, python development and Blender core development.

How about a sitemap like this:

  • docs.blender.org/manual/
  • docs.blender.org/bpy/
    ** docs.blender.org/bpy/introduction/
    ** docs.blender.org/bpy/process/
    ** docs.blender.org/bpy/api/
    ** ...
  • docs.blender.org/dev/
    ** docs.blender.org/dev/process/
    ** docs.blender.org/dev/projects/
    ** docs.blender.org/dev/source/
    *** docs.blender.org/dev/source/overview/
    *** docs.blender.org/dev/source/architecture/
    *** docs.blender.org/dev/source/api/
    *** ...
  • (docs.blender.org/users/?)
  • ...
    De facto, docs.blender.org would be a proper replacement for this page: https:*wiki.blender.org/index.php/Main_Page.

I'm not proposing to move the Wiki to docs.blender.org right now, but I'm asking for a well-considered plan before we start making changes and spreading links on the web.
It's really great so see so much attention put into documentation and I think our infrastructure would become far less confusing by having a central domain for all documentation.

@mont29, my point is simply that `docs.blender.org/api/` is far too vague and may be misleading. We *do* have many APIs, it doesn't matter if they're internal/private or external. The thing is, one person clicking on `docs.blender.org/api/` might expect to see an API documentation for C/C++ plugins, another one might expect to see the documentation of the internal APIs and another one might expect it to show the Python API documentation. The URLs and sitemap structure should make it clear what kind of APIs and corresponding docs are available. --- Also, please consider my point regarding the Wiki. Why should all docs **except of Blender core development ones** be on [docs.blender.org ](https://docs.blender.org/)? If there are good reasons for it, I'd be fine with leaving them in the wiki, but ideally we'd have a central place for **all** documentation - manual, python development and Blender core development. How about a sitemap like this: * `docs.blender.org/manual/` * `docs.blender.org/bpy/` ** `docs.blender.org/bpy/introduction/` ** `docs.blender.org/bpy/process/` ** `docs.blender.org/bpy/api/` ** ... * `docs.blender.org/dev/` ** `docs.blender.org/dev/process/` ** `docs.blender.org/dev/projects/` ** `docs.blender.org/dev/source/` *** `docs.blender.org/dev/source/overview/` *** `docs.blender.org/dev/source/architecture/` *** `docs.blender.org/dev/source/api/` *** ... * (`docs.blender.org/users/`?) * ... De facto, [docs.blender.org ](https:*docs.blender.org/) would be a proper replacement for this page: https:*wiki.blender.org/index.php/Main_Page. I'm not proposing to move the Wiki to [docs.blender.org ](https://docs.blender.org/) right now, but I'm asking for a well-considered plan before we start making changes and spreading links on the web. It's really great so see so much attention put into documentation and I think our infrastructure would become far less confusing by having a central domain for all documentation.
Member

I can see some good points here. I kinda like the idea of having a wiki in docs as well, but is this what we really want? We could move https:*en.blender.org/ under https:*docs.blender.org/wiki/ (even as a test to see how it works) and have https://docs.blender.org/ redirect to /wiki/ by default, I suppose. Your call.

I do agree, however, that we should avoid spreading links all over, and then having those links be removed/changed.

I can see some good points here. I kinda like the idea of having a wiki in docs as well, but is this what we really want? We could move https:*en.blender.org/ under https:*docs.blender.org/wiki/ (even as a test to see how it works) and have https://docs.blender.org/ redirect to `/wiki/` by default, I suppose. Your call. I do agree, however, that we should avoid spreading links all over, and then having those links be removed/changed.
Author
Member

I do not really think that is what he meant. I think I meant that docs.blender.org would be a replacement landing page instead of the one found at https://wiki.blender.org/index.php/Main_Page

I do not really think that is what he meant. I think I meant that docs.blender.org would be a replacement landing page instead of the one found at https://wiki.blender.org/index.php/Main_Page
Member

Do you mean make the current page the new Main_Page for https:*wiki.blender.org/? Or do you mean move the wiki to the "root" path on https:*doc.blender.org/?

Do you mean make the current page the new Main_Page for https:*wiki.blender.org/? Or do you mean move the wiki to the "root" path on https:*doc.blender.org/?

I don’t think dev docs and user docs are same thing, and I don’t think they shall share the same namespace.

User doc has some well-structured, hopefully high-quality expectations. And I do include public API docs here. It has an expected audience of tens of thousands if not millions of people, has a role of “public representation” to some extent, and can be potentially contributed by thousands of users who know how to use Blender. As such, it needs a well structured, and rather stable content, and it is worth spending time on it also on its look/aspect sides, ensure spelling etc. is correct, translate it to other languages… ==> Generated static html (currently, at least).

Dev docs are only for the few people that need to understand the internals of Blender, and for those working on its development. It has an expected audience a hundreds, thousands at most people, very low number of potential writers typically, who often have very few time for it. It is intended to be used for technical descriptions of projects, quick overview of how some code areas work, a place for developers and stakeholders to write whatever they want… As such, we need a very quick and easy, loosely structured way to edit it, and do not care that much about shiny styling, crispy spelling, and so on. ==> wiki.

So I really do not think mixing both of those in a same 'namespace' is a good idea. Too bad developer.blender.org is already taken by phab (though maybe we could use developer.blender.org/wiki for the wiki eg?).

Note that I would not be against some well-structured, high-quality docs about Blender internals in docs.blender.org. It’s just that, afaik, we do not have any currently, and I don’t expect anyone to have the (huge) amount of free time to work on such a project in near future?

Now, regarding /bpy/ instead of /api/… Am not sure. I see the point (bpy is indeed more accurate than api), but for now only public API is bpy. So I don’t think it really matters currently. Should we have other public APIs in the future, we could always move current /api/ into /api/bpy/, and add new ones under same /api/ section…

I don’t think dev docs and user docs are same thing, and I don’t think they shall share the same namespace. User doc has some well-structured, hopefully high-quality expectations. And I do include **public** API docs here. It has an expected audience of tens of thousands if not millions of people, has a role of “public representation” to some extent, and can be potentially contributed by thousands of users who know how to use Blender. As such, it needs a well structured, and rather stable content, and it is worth spending time on it also on its look/aspect sides, ensure spelling etc. is correct, translate it to other languages… ==> Generated static html (currently, at least). Dev docs are only for the few people that need to understand the internals of Blender, and for those working on its development. It has an expected audience a hundreds, thousands at most people, very low number of potential writers typically, who often have very few time for it. It is intended to be used for technical descriptions of projects, quick overview of how some code areas work, a place for developers and stakeholders to write whatever they want… As such, we need a very quick and easy, loosely structured way to edit it, and do not care that much about shiny styling, crispy spelling, and so on. ==> wiki. So I really do not think mixing both of those in a same 'namespace' is a good idea. Too bad developer.blender.org is already taken by phab (though maybe we could use `developer.blender.org/wiki` for the wiki eg?). Note that I would not be against some well-structured, high-quality docs about Blender internals in docs.blender.org. It’s just that, afaik, we do not have any currently, and I don’t expect anyone to have the (huge) amount of free time to work on such a project in near future? Now, regarding `/bpy/` instead of `/api/`… Am not sure. I see the point (bpy is indeed more accurate than api), but for now only public API is bpy. So I don’t think it really matters currently. Should we have other public APIs in the future, we could always move current `/api/` into `/api/bpy/`, and add new ones under same `/api/` section…
Member

I think that there is a built-in phabricator wiki. Not to say we should switch to that (@Sergey would know best here), but it would conflict with the path a bit potentially?

I admit that it does seem a little odd to have 3 items listed on the landing page for docs.blender.org now (api/manual/wiki), but one of them is on another domain.

I think that there is a built-in phabricator wiki. Not to say we should switch to that (@Sergey would know best here), but it would conflict with the path a bit potentially? I admit that it does seem a little odd to have 3 items listed on the landing page for `docs.blender.org` now (api/manual/wiki), but one of them is on another domain.
Member

In #50466#414036, @dmcgrath wrote:
Do you mean make the current page the new Main_Page for https:*wiki.blender.org/? Or do you mean move the wiki to the "root" path on https:*doc.blender.org/?

None of these, I was just pointing out that the entry point to all Blender documentation currently is https:*wiki.blender.org/, and in future with the new docs infrastructure it would be https:*docs.blender.org/. Both sites can stay as they are for now (as long as we keep wiki.blender.org), just saying ;)


In #50466#414037, @mont29 wrote:
I don’t think dev docs and user docs are same thing, and I don’t think they shall share the same namespace.

User doc has some well-structured, hopefully high-quality expectations. And I do include public API docs here. It has an expected audience of tens of thousands if not millions of people, has a role of “public representation” to some extent, and can be potentially contributed by thousands of users who know how to use Blender. As such, it needs a well structured, and rather stable content, and it is worth spending time on it also on its look/aspect sides, ensure spelling etc. is correct, translate it to other languages… ==> Generated static html (currently, at least).

Dev docs are only for the few people that need to understand the internals of Blender, and for those working on its development. It has an expected audience a hundreds, thousands at most people, very low number of potential writers typically, who often have very few time for it. It is intended to be used for technical descriptions of projects, quick overview of how some code areas work, a place for developers and stakeholders to write whatever they want… As such, we need a very quick and easy, loosely structured way to edit it, and do not care that much about shiny styling, crispy spelling, and so on. ==> wiki.

So I really do not think mixing both of those in a same 'namespace' is a good idea. Too bad developer.blender.org is already taken by phab (though maybe we could use developer.blender.org/wiki for the wiki eg?).

I don't see why we shouldn't have both under the same domain though? https://docs.blender.org/ would be split into some main categories. These categories link to completely different kind of docs anyway (e.g. Manual vs. BPY API docs), I don't see an issue with having the dev docs there as well, just because they are less polished?
Also, I'd consider the Python API docs far less polished as the manual (contains spelling mistakes, [totally unhelpful descriptions ]], [ https:*docs.blender.org/api/blender_python_api_current/bpy.types.Panel.html?highlight=xxx#bpy.types.Panel.text | XXXes , ...). So following your argumentation the Python API had to stay separate from docs.blender.org as well ;)

Note that I'm not proposing to move the dev docs out of the wiki, but just to move them to a different URN to make our infrastructure less confusing - e.g. wiki.blender.org/Dev:foo/ -> docs.blender.org/dev/foo/

Now, regarding /bpy/ instead of /api/… Am not sure. I see the point (bpy is indeed more accurate than api), but for now only public API is bpy. So I don’t think it really matters currently. Should we have other public APIs in the future, we could always move current /api/ into /api/bpy/, and add new ones under same /api/ section…

That's the thing, we shouldn't just use /api/ for Python docs now and decide later to move them to something else while repurposing /api/ for something different (eg. landing page for public APIs). We'd break all existing links to /api/ on the web. Hence my call for choosing namespaces carefully :)

In my idea, also non-API Python docs like this would be under /bpy/. That's why I'd prefer docs.blender.org/bpy/... as opposed to docs.blender.org/api/....

> In #50466#414036, @dmcgrath wrote: > Do you mean make the current page the new Main_Page for https:*wiki.blender.org/? Or do you mean move the wiki to the "root" path on https:*doc.blender.org/? None of these, I was just pointing out that the entry point to all Blender documentation currently is https:*wiki.blender.org/, and in future with the new docs infrastructure it would be https:*docs.blender.org/. Both sites can stay as they are for now (as long as we keep wiki.blender.org), just saying ;) --- > In #50466#414037, @mont29 wrote: > I don’t think dev docs and user docs are same thing, and I don’t think they shall share the same namespace. > > User doc has some well-structured, hopefully high-quality expectations. And I do include **public** API docs here. It has an expected audience of tens of thousands if not millions of people, has a role of “public representation” to some extent, and can be potentially contributed by thousands of users who know how to use Blender. As such, it needs a well structured, and rather stable content, and it is worth spending time on it also on its look/aspect sides, ensure spelling etc. is correct, translate it to other languages… ==> Generated static html (currently, at least). > > Dev docs are only for the few people that need to understand the internals of Blender, and for those working on its development. It has an expected audience a hundreds, thousands at most people, very low number of potential writers typically, who often have very few time for it. It is intended to be used for technical descriptions of projects, quick overview of how some code areas work, a place for developers and stakeholders to write whatever they want… As such, we need a very quick and easy, loosely structured way to edit it, and do not care that much about shiny styling, crispy spelling, and so on. ==> wiki. > > So I really do not think mixing both of those in a same 'namespace' is a good idea. Too bad developer.blender.org is already taken by phab (though maybe we could use `developer.blender.org/wiki` for the wiki eg?). I don't see why we shouldn't have both under the same domain though? https://docs.blender.org/ would be split into some main categories. These categories link to completely different kind of docs anyway (e.g. Manual vs. BPY API docs), I don't see an issue with having the dev docs there as well, just because they are less polished? Also, I'd consider the Python API docs far less polished as the manual (contains spelling mistakes, [totally unhelpful descriptions ]], [[ https:*docs.blender.org/api/blender_python_api_current/bpy.types.Panel.html?highlight=xxx#bpy.types.Panel.text | XXXes ](https:*docs.blender.org/api/blender_python_api_current/bpy.types.BlendDataCurves.html#bpy.types.BlendDataCurves.tag), ...). So following your argumentation the Python API had to stay separate from docs.blender.org as well ;) Note that I'm not proposing to move the dev docs out of the wiki, but just to move them to a different URN to make our infrastructure less confusing - e.g. `wiki.blender.org/Dev:foo/` -> `docs.blender.org/dev/foo/` > Now, regarding `/bpy/` instead of `/api/`… Am not sure. I see the point (bpy is indeed more accurate than api), but for now only public API is bpy. So I don’t think it really matters currently. Should we have other public APIs in the future, we could always move current `/api/` into `/api/bpy/`, and add new ones under same `/api/` section… That's the thing, we shouldn't just use `/api/` for Python docs now and decide later to move them to something else while repurposing `/api/` for something different (eg. landing page for public APIs). We'd break all existing links to `/api/` on the web. Hence my call for choosing namespaces carefully :) In my idea, also non-API Python docs like [this ](https://wiki.blender.org/index.php/Dev:Py/Scripts) would be under `/bpy/`. That's why I'd prefer `docs.blender.org/bpy/...` as opposed to `docs.blender.org/api/...`.

@dmcgrath I'm up for some CSS tweaks in the upcoming days, I'll message you directly, also about symlinks and renames.

Regarding /api vs /bpy, I see your point @JulianEisel, but the chances of getting any other API next to it in the future are close to none (and can be solved by adding a new language after the version, like /api/2.80/python/).

Further:

  • Wiki stays for dev docs (see @mont29), which should be easy to edit and interact with. There is no reason to move dev docs now, we can point to the Dev: section of the wiki and deal with it later.
  • Wiki itself can be improved in many ways, and that's for a future discussion.
  • Please let's follow this convention /api/2.78b/ (/api url prefix and dot-separated digits are a standard in API documentation URLs)

Priority should be to finalize (user) API and manual URLs and pages.

@dmcgrath I'm up for some CSS tweaks in the upcoming days, I'll message you directly, also about symlinks and renames. Regarding `/api` vs `/bpy`, I see your point @JulianEisel, but the chances of getting any other API next to it in the future are close to none (and can be solved by adding a new language after the version, like `/api/2.80/python/`). Further: - Wiki stays for dev docs (see @mont29), which should be easy to edit and interact with. There is no reason to move dev docs now, we can point to the Dev: section of the wiki and deal with it later. - Wiki itself can be improved in many ways, and that's for a future discussion. - Please let's follow this convention `/api/2.78b/` (`/api` url prefix and dot-separated digits are a standard in API documentation URLs) Priority should be to finalize (user) API and manual URLs and pages.
Member

In #50466#414050, @JulianEisel wrote:
Note that I'm not proposing to move the dev docs out of the wiki, but just to move them to a different URN to make our infrastructure less confusing - e.g. wiki.blender.org/Dev:foo/ -> docs.blender.org/dev/foo/

I don't think that you don't want to have a wiki at the root path like docs.blender.org/. It's not recommended officially, IIRC, and it would just make things a headache when we add stuff that conflicts in the same namespace (ie: we have /manual and /api and then some user in the wiki creates such a path). At the absolute minimum, the wiki should be at docs.blender.org/wiki/ with a redirect from the landing page redirecting to it on a LocationMatch of "^/$". At least that is my advice.

@fsiddi sounds good. Chat with you later o/

EDIT: Well, not technically a LocationMatch, but a RewriteRule. Pretty much the same idea in this context, however.

> In #50466#414050, @JulianEisel wrote: > Note that I'm not proposing to move the dev docs out of the wiki, but just to move them to a different URN to make our infrastructure less confusing - e.g. `wiki.blender.org/Dev:foo/` -> `docs.blender.org/dev/foo/` I don't think that you don't want to have a wiki at the root path like `docs.blender.org/`. It's not recommended officially, IIRC, and it would just make things a headache when we add stuff that conflicts in the same namespace (ie: we have `/manual` and `/api` and then some user in the wiki creates such a path). At the absolute minimum, the wiki should be at `docs.blender.org/wiki/` with a redirect from the landing page redirecting to it on a `LocationMatch` of "^/$". At least that is my advice. @fsiddi sounds good. Chat with you later o/ EDIT: Well, not technically a `LocationMatch`, but a `RewriteRule`. Pretty much the same idea in this context, however.

Added subscriber: @francesco

Added subscriber: @francesco

@fsiddi re /api/, agreed, will do the change in names soonish :)

@fsiddi re `/api/`, agreed, will do the change in names soonish :)

Added subscriber: @RayMairlot

Added subscriber: @RayMairlot

So, finally found time to update API doc layout, should now match what we decided above.

Also note that I added an /api/blender2.8/ entry, think it’s time we get some easily accessible doc about that one too. ;)

So, finally found time to update API doc layout, should now match what we decided above. Also note that I added an `/api/blender2.8/` entry, think it’s time we get some easily accessible doc about that one too. ;)
Author
Member

Changed status from 'Open' to: 'Resolved'

Changed status from 'Open' to: 'Resolved'
Aaron Carlisle self-assigned this 2017-04-11 05:52:33 +02:00
Author
Member

Thanks for everyone who helped move this over.

Thanks for everyone who helped move this over.
Sign in to join this conversation.
No Milestone
No project
No Assignees
8 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: blender/blender-manual#50466
No description provided.