diff --git a/conf.py b/conf.py index 4a222281..3ddd50a0 100644 --- a/conf.py +++ b/conf.py @@ -48,14 +48,16 @@ 'Eric': ('Eric Holscher', 'http://ericholscher.com'), 'Anthony': ('Anthony Johnson', 'http://ohess.org'), 'David': ('David Fischer', ''), - 'Safwan': ('Safwan Rahman', 'https://github.com/safwanrahman/') + 'Safwan': ('Safwan Rahman', 'https://github.com/safwanrahman/'), + 'Santos': ('Santos Gallegos', 'https://github.com/stsewd/'), } blog_default_author = 'Eric' blog_locations = { 'PDX': ('Portland, Oregon', 'http://www.portlandhikersfieldguide.org/'), 'SAN': ('San Diego, CA', ''), - 'DHA': ('Dhaka, Bangladesh', 'https://wikitravel.org/en/Bangladesh') + 'DHA': ('Dhaka, Bangladesh', 'https://wikitravel.org/en/Bangladesh'), + 'CUE': ('Cuenca, Ecuador', ''), } blog_default_location = 'PDX' blog_feed_archives = True diff --git a/configuration-file-v2.rst b/configuration-file-v2.rst new file mode 100644 index 00000000..fe34bc69 --- /dev/null +++ b/configuration-file-v2.rst @@ -0,0 +1,149 @@ +.. post:: February 20, 2019 + :tags: feature + :author: Santos + :location: CUE + +New Configuration File +====================== + +We are happy to announce the new version of the `Read the Docs configuration file`_ (v2). + +.. _Read the Docs configuration file: https://docs.readthedocs.org/en/latest/config-file/v2 + +.. code-block:: yaml + + version: 2 + python: + version: 3.7 + install: + - requirements: docs/requirements.txt + sphinx: + configuration: docs/conf.py + formats: all + +If you are a recurrent Read the Docs user, +chances are that you've configured your projects using a `.readthedocs.yml` file. + +Using the web interface is quick, +but the main advantages of using a configuration file over the web interface are: + +- Some settings are only available using a configuration file. + We are moving away from using the web interface. + +- The settings are per version rather than per project. + This would allow different versions of docs to be built with different versions of Python + or different requirements. + +- The settings live in your VCS. + +- Reproducible build environments over time. + +What did we change in the new version? +-------------------------------------- + +**All the configurations from the web interface**. +In the past not all options from the web interface were available in the configuration file, +now they are! +We also reorganized and renamed some options to make them more clear. + +**New defaults**, +we don't merge the values from the web interface, +because this was confusing our users. +This also allows us to change defaults without breaking existing projects. + +**More flexible installations**, +users can install their projects in a more flexible way, +like multiple requirements and packages from different locations. + +**Strict validation** for invalid options in the configuration file, +to avoid typos and provide more feedback on invalid configurations. + +New features +------------ + +- MkDocs support (previously it was only supported from the web interface). + +.. code-block:: yaml + + version: 2 + mkdocs: + configuration: mkdocs.yml + fail_on_warning: true + +- More control over Sphinx. + +.. code-block:: yaml + + version: 2 + sphinx: + builder: html + configuration: docs/source/conf.py + fail_on_warning: true + +- Control over submodules, we don't always need them all to build our docs. + +.. code-block:: yaml + + version: 2 + submodules: + include: + - third-party/dependency + recursive: true + +- Support for multiple packages/requirements installations. + +.. code-block:: yaml + + version: 2 + python: + version: 3.7 + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt + - method: pip + path: package + +Future improvements +------------------- + +We are already planning new features to support more projects and use cases. + +**Pipfile support**, this is one of our more requested features, +and we are going to ship it soon. +Keep an eye in `#3181`_. + +**Show the configuration used in each build**. +We want to make more explicit to the users how we are building their docs. + +**Redirects per version** of your docs. +Currently users can define global redirects only from the web interface, +this is hard to maintain and review. +One use case is when you change your docs structure between versions. +Keep track of this upcoming feature in `#4221`_. + +.. _#3181: https://github.com/rtfd/readthedocs.org/issues/3181 +.. _#4221: https://github.com/rtfd/readthedocs.org/issues/4221 + +Start using it +-------------- + +The full docs about the new version are available `here `__. + +If you are using the v1, you can update to v2 following our `migration docs`_. + +.. _migration docs: http://docs.readthedocs.org/en/latest/config-file/v2#migrating-from-v1 + +If you have a problem using the configuration file, feel free to `file an issue`_. + +.. _`file an issue`: http://github.com/rtfd/readthedocs.org/issues + +Summer internship +----------------- + +This project was part of my summer internship in Read the Docs, +it was held at the same time as the Google Summer of Code (GSoC) project. + +Thanks to the `core team`_ (Anthony, David, Eric, and Manuel) for helping me in the process. +Thanks to all contributors, sponsors, donors and users of Read the Docs to make the project sustainable. + +.. _core team: https://docs.readthedocs.io/en/latest/team.html#development-team