Config file v2 docs #4451

stsewd · 2018-07-30T20:21:18Z

This should be merged as the last step of the configuration file project. We need to add a redirect after this is merged (yaml-config.html -> config-file/v1.html).

I added a changelog to facilitate the migration from v1 and also a link from v1 to v2

davidfischer

This is looking pretty good.

docs/config-file/index.rst

davidfischer · 2018-07-30T23:40:50Z

docs/config-file/index.rst

+
+.. note::
+
+   Using a configuration file is the recomended way of using Read the Docs,


recomended -> recommended

davidfischer · 2018-07-30T23:41:43Z

docs/config-file/index.rst

+.. note::
+
+   Using a configuration file is the recomended way of using Read the Docs,
+   the web interface would be deprecated,


Should we give a deprecation timeline? Should we urge that new projects should always use the config file?

Not sure about the exact time. But Anthony mention that we will use a feature flag to block the ui, so new projects still can build with no configuration file, but if they need further configuration a config file is needed. I'm a little worried about projects moving to rtd (where older versions can't be updated)

docs/config-file/v2.rst

davidfischer · 2018-07-30T23:49:42Z

docs/index.rst

@@ -42,7 +42,7 @@ Information about development is also available:
   features
   support
   faq
-   yaml-config
+   config-file/index


This is just a note that after merging this we should add a redirect for our docs (yaml-config.html -> config-file/v1.html)

docs/config-file/v2.rst

agjohnson

Great addition! The only thing missing from the v2 docs is a warning "These features are still in development and are not yet supported" and maybe add a warning about v2 config is not enabled by default for projects yet. Alternatively, this PR just sits around until everything is ready for the v2 config and we've removed the feature flag requirement for use. I'd probably prefer to get this merged early and have warnings for users -- maybe this way we can get some users for testing.

agjohnson · 2018-08-02T17:16:55Z

docs/config-file/index.rst

+Configuration File
+==================
+
+Additionally to the admin panel of your project,


Additionally -> In addition

Also, probably just In addition to using the admin panel of your project to configure your project,. Otherwise this sentence isn't clear.

Isn't redundant to say of your project twice?

docs/config-file/index.rst

docs/config-file/v1.rst

docs/config-file/v2.rst

agjohnson · 2018-08-02T17:29:47Z

docs/config-file/v2.rst

+
+Formats of the documentation to be built.
+
+* Type: ``list``


So, not sure if it makes sense to redo this doc or the v1 docs, but reST already has 2 list types that work better than DIY-ing a list type via a bullet list: definition lists[1] and field lists[2]. Instead of a bullet list, I think a field list works best here:

:Type: ``list`` :Options: ``htmlzip``, ``pdf``, ``epub`` :Default: ``[]``

The output is a bit more tuned than a bullet list, for example on our theme:
https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/lists_tables.html#field-list

I know this pattern was copied from the original v1 docs, and they got this wrong as well, so not sure if we change either.

I love how field list is rendered

docs/config-file/v2.rst

stsewd · 2018-08-02T18:51:35Z

Alternatively, this PR just sits around until everything is ready for the v2 config and we've removed the feature flag requirement for use.

@agjohnson that was the original idea. I like the idea of having "test users" too. Let me know how you want to ship this :). Thanks for the review!

agjohnson · 2018-08-03T00:26:52Z

docs/config-file/v2.rst

@@ -1,8 +1,8 @@
 Configuration File V2
 =====================

-Read the Docs support configuring builds with a YAML file.
-The file, ``.readthedocs.yml``, must be in the root directory of your project.
+Read the Docs support configuring your documentation builds with a YAML file.


Missed this the first pass, support -> supports

agjohnson · 2018-08-03T00:28:40Z

We talked more on this and i think settled on blocking this PR on merge until the v2 was publicly usable. We'll need to remember to come back to this PR for any doc updates for the config until then though.

docs/doc_extensions.py

humitos

This looks pretty solid! I like it!

Although, there are some changes that I'd like to see before merging this.

I found that sometimes we are using a global example and not a specific example for each option and sometimes we are using both. I'm not sure if this is on purpose.

What's best? Use both examples, use a mix (as it is right now) or use just the specific one?

humitos · 2018-08-15T14:17:39Z

docs/config-file/index.rst

+- The settings are per version rather than per project.
+- The settings live in your VCS.
+
+.. note::


A .. tip:: makes more sense here to me.

docs/config-file/index.rst

humitos · 2018-08-15T14:22:48Z

docs/conda.rst

-
-	conda:
-	    file: environment.yml
+Conda support is avalible using a :doc:`config-file/index`.


If we are removing the example completely, it would be good to link to the proper section of the config file that explains this. Otherwise, if we point the readers to the Index they will need to start from the beginning.

This is something I was thinking a lot, now that we have two versions, is kind of tricky to point to a specific one :/. Maybe always linking to the latest version?

Yes. I think we should point the user to the one we want them to use. In this case v2.

humitos · 2018-08-15T14:26:20Z

docs/config-file/v1.rst


-.. warning:: This feature is in a beta state.
-             Please file an `issue`_ if you find anything wrong.
+.. note::


.. warning:: is better here.

Also, this block should mention that v1 shouldn't be used.

humitos · 2018-08-15T14:26:38Z

docs/config-file/v1.rst


+   The version 2 of the configuration file is now avaliable.
+   See the :doc:`new features and how to migrate from v1 <v2>`.


Link to the proper section for migration here instead of the root of v2.

Maybe two links are needed in this sentence:

new features

how to migrate from v1

docs/config-file/v2.rst

humitos · 2018-08-15T15:07:43Z

docs/config-file/v2.rst

+.. note::
+
+   Not all settings in the web interface are per version, but are per project.
+   Those settings aren't supported via the configuration file (like ``Default branch``).


I suppose we should have a specific list with all the settings that can't be managed via the YAML file.

Need to check the admin panel p:

humitos · 2018-08-15T15:10:29Z

docs/doc_extensions.py

@@ -6,11 +6,19 @@
 djangosetting
    Output an inline literal of the corresponding setting value. Useful for
    keeping documentation up to date without editing on settings changes.
+
+supportedversions


I'd like to have a more descriptive name for this, like dockerpyversions or buildpyversions or dockerimagepyversions or similar.

supportedversions is too general.

buildpyversions I like this one p:

humitos · 2018-08-15T15:12:04Z

docs/guides/build-using-too-many-resources.rst

@@ -10,7 +10,8 @@ there are a couple fixes that you might try.
 Reduce formats you're building
 ------------------------------

-You can change the formats of docs that you're building with our YAML file's :ref:`yaml-config:Formats` option.
+You can change the formats of docs that you're building with our :doc:`/config-file/index`


Link to the specific format option.

humitos · 2018-08-15T15:12:50Z

docs/guides/specifying-dependencies.rst

-    requirements_file: requirements.txt
-
-See :doc:`yaml-config` for setting up the .yml file
+The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file. 


Link to the specific section.

stsewd · 2019-01-22T22:49:30Z

This shouldn't be blocked anymore, but I think we should merge it after doing a deploy on .org

stsewd · 2019-01-22T22:52:25Z

docs/config-file/v2.rst

+:Type: ``number``
+:Default: ``3``
+
+python.install


Not really sure if this whole section is clear. Now that we accept a list with different keys.

stsewd · 2019-01-22T22:59:02Z

docs/config-file/v2.rst

+   This is ignored if there aren't submodules to clone.
+
+Schema
+------


Not sure if this section is relevant

I think it's OK!

humitos

I noted some things, request some changes and made some suggestions that we should discuss before merging this.

Some of them are related with the implementation itself also and affects default values (#5155)

docs/config-file/v1.rst

docs/config-file/v2.rst

humitos · 2019-01-23T11:32:20Z

docs/config-file/v2.rst

+
+Install packages from a requirements file.
+
+The path to the requirements file, relative to the root of the project.


The path to the requirements file must be relative to the root of the project.

(added "must be" and removed the comma)

This could be a .. note:: after showing the example. I think it will be clearer.

This is a description of the key below, it also works as a separator for the list of keys, I wasn't sure how to list them

humitos · 2019-01-23T11:34:22Z

docs/config-file/v2.rst

+
+:Key: ``requirements``
+:Type: ``path``
+:Required: ``true``


This key python.install.requirements it's not required as far as I know.

What it means here that can't be empty. Again, not sure how to list the values for the install key

I didn't compile the docs, but reading it from the diff I found they are good.

I wouldn't use :Required: on these cases, though. I think it's confusing like "I need to have a requirements.txt to build my docs"

So, I just put a default value to the whole python.install, hope that make it more clear.

docs/config-file/v2.rst

humitos · 2019-01-23T12:05:15Z

docs/config-file/v2.rst

+Migrating from the web interface
+--------------------------------
+
+This should be pretty straightforward,


Reading section is not too clear what I have to do as a user.

Find the settings that match from the web interface

humitos · 2019-01-23T12:07:02Z

docs/guides/specifying-dependencies.rst

-
-See :doc:`/yaml-config` for setting up the .yml file
+The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file, 
+see :ref:`config-file/v2:Requirements file`.

 Using the project admin dashboard
 ---------------------------------


We may suggest the user that it's preferable to use the config file here, I suppose.

We just mention that above

ericholscher

I took a peek, but will wait until @humitos's feedback is addressed to give it a full review, so we don't double up.

docs/config-file/v2.rst

Co-Authored-By: stsewd <[email protected]>

ericholscher

I think we should ship this, and we can deal with the smaller changes as we get feedback from users. 👍

ericholscher · 2019-01-29T20:28:38Z

docs/config-file/v2.rst

+
+This should be pretty straightforward,
+just go to the :guilabel:`Admin` > :guilabel:`Advanced settings`,
+and find their respective setting in :ref:`here <config-file/v2:Supported settings>`.


Can we generate a config automatically from their existing DB entries? It would be neat to go to /dashboard/project/yaml/ and get a generated YAML file with their existing build config.

This shouldn't block this PR, but would be a 💯 migration step.

Yeah, we actually need to do it from version. We have this issue opened #4746

stsewd · 2019-01-29T22:40:30Z

We need to add a redirect after this is merged: yaml-config.html -> config-file/v1.html.

ericholscher · 2019-01-29T22:50:52Z

We need to add a redirect after this is merged: yaml-config.html -> config-file/v1.html.

You can add it now, and it will be ignored til it 404's.

stsewd · 2019-01-29T22:51:53Z

I don't have permissions there p:

ericholscher · 2019-01-29T22:54:07Z

You do now! 🎉

ericholscher · 2019-01-30T14:49:15Z

@stsewd we need to remove the feature flag now, I think?

davidfischer reviewed Jul 31, 2018

View reviewed changes

agjohnson requested changes Aug 2, 2018

View reviewed changes

agjohnson added this to the YAML File Completion milestone Aug 2, 2018

agjohnson reviewed Aug 3, 2018

View reviewed changes

stsewd force-pushed the config-file-v2-docs branch from 2b6841e to bb04aa6 Compare August 6, 2018 18:10

stsewd commented Aug 6, 2018

View reviewed changes

docs/doc_extensions.py Outdated Show resolved Hide resolved

stsewd force-pushed the config-file-v2-docs branch from 689229b to 7176e4b Compare August 10, 2018 16:30

humitos requested changes Aug 15, 2018

View reviewed changes

stsewd mentioned this pull request Aug 15, 2018

Use ignore keyword to ignore the requirements file #4523

Closed

agjohnson added the Status: blocked Issue is blocked on another issue label Aug 27, 2018

stsewd force-pushed the config-file-v2-docs branch from b2592d8 to 16e5a1e Compare August 30, 2018 17:07

stsewd mentioned this pull request Sep 4, 2018

Mention more the usage of the rtd configuration file #3193

Closed

stsewd force-pushed the config-file-v2-docs branch from bccd18a to 240e513 Compare October 4, 2018 17:02

stsewd mentioned this pull request Oct 10, 2018

Extend install option from config file (v2, schema only) #4732

Merged

stsewd mentioned this pull request Oct 25, 2018

Add docs about Pipfile support #4809

Closed

stsewd added 13 commits November 21, 2018 12:40

Rename docs from v1

76af98a

Add docs for v2

d09b3c2

Add docs for sphinx.buider

61eff39

Typos

b2823be

Use same name

3d61b5c

List all filenames in index

702ee70

Fix ref

1a840ac

Better sentence

f50b033

Don't mention the deprecation yet

8b67757

Link the filename to just one place

aa9455d

Change bullet list to definition list

a4544d9

Typo

c1f34a9

Typo

66f53f8

stsewd added 5 commits January 22, 2019 14:14

Update migration guide

ebf3b0d

Reword

d08283c

Merge branch 'master' into config-file-v2-docs

2607216

Fix link

b13a5b6

Update extension

d6c9e40

stsewd removed the Status: blocked Issue is blocked on another issue label Jan 22, 2019

Clean up

c512420

stsewd commented Jan 22, 2019

View reviewed changes

stsewd requested a review from a team January 22, 2019 22:59

humitos requested changes Jan 23, 2019

View reviewed changes

ericholscher reviewed Jan 23, 2019

View reviewed changes

docs/config-file/v2.rst Outdated Show resolved Hide resolved

ericholscher and others added 5 commits January 23, 2019 11:15

Update docs/config-file/v2.rst

9fe4a1d

Co-Authored-By: stsewd <[email protected]>

Feedback

f5d3ec4

Be more explicit about python.install default

7f520a4

More generic description for submodules

5e0b771

Fix broken link

329286f

humitos mentioned this pull request Jan 23, 2019

Set python3 as default interpreter #3581

Merged

Merge branch 'master' into config-file-v2-docs

54ffc0e

stsewd requested a review from a team January 29, 2019 19:35

ericholscher approved these changes Jan 29, 2019

View reviewed changes

Merge branch 'master' into config-file-v2-docs

eb1cd4e

Update versions

f4a5f07

stsewd merged commit 538ba07 into readthedocs:master Jan 29, 2019

stsewd deleted the config-file-v2-docs branch January 29, 2019 23:47


		.. note::

		Using a configuration file is the recomended way of using Read the Docs,


		The version 2 of the configuration file is now avaliable.
		See the :doc:`new features and how to migrate from v1 <v2>`.


		Install packages from a requirements file.

		The path to the requirements file, relative to the root of the project.

Config file v2 docs #4451

Config file v2 docs #4451

Conversation

stsewd commented Jul 30, 2018 • edited Loading

davidfischer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Aug 2, 2018

Choose a reason for hiding this comment

agjohnson commented Aug 3, 2018

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Jan 22, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Jan 29, 2019

ericholscher commented Jan 29, 2019

stsewd commented Jan 29, 2019

ericholscher commented Jan 29, 2019

ericholscher commented Jan 30, 2019

stsewd commented Jul 30, 2018 •

edited

Loading