Как заставить Sphinx генерировать "последние изменения" из времени доступа к исходным файлам для отдельных страниц?

Question

Я работаю над проектом документации со sphinx и темой ReadTheDocs. Исходные файлы находятся в git-репозитории на gitlab, и я использую автоматическое тестирование для проверки правильности сборки документации при каждом слиянии с основной веткой. Я могу хранить успешно созданные html-файлы на gitlab и синхронизировать их с моим частным сервером. Однако поскольку документация всегда создается с нуля во время автоматических тестов, флаг "Последнее изменение" на страницах всегда указывается во время последней сборки страниц. Я хотел бы избежать этого и оставить флаг "Last Modified" в значении true, т. Е. Чтобы он отображал фактическое время последней модификации исходного файла.rst. Есть способ сделать это?

Answer 1

Я знаю, что немного опоздал, но я только что создал небольшое расширение Sphinx, которое получает время "последнего изменения" от Git:

https://github.com/mgeier/sphinx-last-updated-by-git/

Answer 2

Единственный способ, которым мне удавалось сделать это в прошлом, это использовать что-то вроде атрибутов Git. Прочитайте эту страницу:

https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes

Особенно обратите внимание на раздел "Расширение ключевых слов".

Answer 3

Вы можете использовать директиву Date первого числа.

Вверху или внизу ваших первых файлов, включите текст ниже

.. |date| date::

Last Updated on |date|

В окончательной сборке эта дата будет обновлена ​​только после обновления исходного кода.

Ссылка: https://faculty.math.illinois.edu/~gfrancis/illimath/windows/aszgard_mini/movpy-2.0.0-py2.4.4/manuals/docutils/ref/rst/directives.html

Answer 4

Основываясь на ответе Кевина Хорна, я добавил следующее в свой скрипт сборки, который автоматически выполняется на сервере gitlab для непрерывной интеграции:

#!/bin/bash

#=============================================================================
# Automatically add last modified date according to last commit date
#=============================================================================

# first store all the files that are modified;
# don't want them to be added automatically to the commit
# without you noticing!

modfiles=`git ls-files -m`



# Add or update dates to the file

for f in `find . -name "*.rst"`; do

    lastline=`tail -n 1 $f`
    llstrip="$(echo -e "${lastline}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
    commdate=`git log -n 1 --date=short --pretty=format:%cd -- $f`

    if [[ "$llstrip" = "*Page last edited"* ]]; then
        sed -i "s/\*Page last edited [0-9]*-[0-9]*-[0-9]*\*/\*Page last edited ${commdate}\*/" $f
    else
        echo "" >> $f
        echo "" >> $f
        echo '*Page last edited' "$commdate"'*' >> $f
    fi;

done


# Now you're done adding dates to the files.
# Quietly add the changed files to the last commit.
# But only do so for files that were included in the commits 
# since your branch deviated from the master,
# don't add untracked files without permission!

mybranch=`git rev-parse --abbrev-ref HEAD`
deviat=`git merge-base $mybranch master`

i=0
looping=true
while $looping; do
    i=$((i+1))
    cmtlist=`git log -n $i --format=%H`

    if [[ ${cmtlist} == *${deviat}* ]]; then
        looping=false
    fi
done

#cmtlist now contains all commit hashes since the branch deviated from the master.

added=false
for f in `git ls-files -m`; do
    comm=`git log -n 1 --pretty=format:%H -- $f`
    if [[ ${cmtlist} == *${comm}* ]]; then

        if [[ ${modfiles} == *${f}* ]]; then
            # if changes in file not commited
            continue
        else
            git add $f
            added=true
        fi
    fi
done


if $added; then
    git commit --amend --no-edit --quiet
else
    echo 'Quickbuild script: nothing to add'
fi




#=============================================================================
# Make clean then rebuild
#=============================================================================

# rm `find . -name "*checkpoint.ipynb"` > /dev/null 2>&1
make clean
make html





exit 0

Это добавит или обновит дату последней фиксации, в которой любой файл.rst был изменен, до конца файла.rst. Внесенные изменения будут незаметно добавлены в коммит при условии, что файлы были изменены, поскольку ветвь отклоняется от основной ветки и не имеет изменений. Во время автоматического тестирования gitlab фиксация завершится неудачно, но это не имеет значения, потому что правильные даты уже будут в файле, а правильные HTML-страницы могут быть созданы и синхронизированы с моим сервером с помощью cronjob со стороны моего сервера. Запустив скрипт вручную, чтобы быстро очистить и восстановить, он все же будет работать.

Проблема с решениями, предложенными Кевином Хорном, состоит в том, что он работает только локально, потому что вы настраиваете свой git config так, что он автоматически расширяет переменные при каждом коммите; Но мне бы пришлось заставить всех моих сотрудников делать то же самое, поэтому я выбрал этот вариант.